Writing effective Claude Code skills

Skills are the most underrated feature in Claude Code. I use dozens of them covering everything from Git commits to blog article creation. Most developers have none, or one or two copied from a tutorial. This article shows how to write skills that work in production: the structure, the loading mechanism, the patterns I've identified after months of iteration, and the common mistakes. What a skill is A skill is a folder containing a SKILL.md file. The file combines a YAML frontmatter (metadata) and a Markdown body (instructions). When the user types /skill-name or phrases a request that matches the description, Claude loads the instructions and follows them. The official documentation covers installation and basic syntax. commit-push/ SKILL.md # required: metadata + instructions references/ # optional: detailed docs scripts/ # optional: executable code assets/ # optional: templates, static files The SKILL.md format is an open standard created by Anthropic and adopted by other agent products like Cursor. A skill written for Claude Code works as-is in these tools. Progressive disclosure: why it matters The loading mechanism is the most important aspect to understand. Without it, you write skills that are too large and waste context, or too vague and never trigger. Loading happens in three levels: Level 1 - Discovery (~100 tokens per skill). Only the name and description from the frontmatter are injected into the system prompt at the start of each session. Claude knows the skill exists and when it applies. Even with dozens of active skills, that's only a few thousand tokens - negligible in a 200K context. Level 2 - Activation (