The Description Is the Skill
Your Claude Code skill is probably never loading.
The body sits on disk, polished and unread, because Claude never decided it was relevant. At startup only the name and description from each skill enter the model's context, roughly a hundred tokens apiece [1]. The rest stays dormant until the trigger fires.
Selection is the work.
Selection beats substance
Skills load through progressive disclosure. Claude scans the YAML frontmatter of every available skill at session start and reads only the name and description. When you give it a task, it checks whether any description matches. Match, and the full SKILL.md loads. Miss, and your instructions never enter context [2].
This single fact reorganizes the priority stack. The body of your skill is conditional. The description is not. Optimizing the body before the description is like polishing chrome on a car that will not start.
Most skill authors do it anyway. They write the body first, then summarize the body into a description. The order is inverted from the order that matters.
The Tequila inversion
The usual advice about authoring skills reads like a checklist:
- Write clear instructions
- Include examples
- Keep skills focused
- Use markdown headers
- Test before shipping
Forbid yourself from any of it. What remains is the actual problem: selection. A skill never selected is a skill never tested, never refined, never useful. The whole craft of skill authoring collapses into one question.
Under what phrasings of user intent does this skill trigger?
That question lives in the description.
The 1,536-character contract
The description field has a hard ceiling. Claude Code caps the combined description and trigger metadata at 1,536 characters, and that ceiling is the entire budget for skill authoring [3]. Everything outside the ceiling is overflow.
Two jobs share the budget:
- State what the skill does
- State when Claude should invoke it
Anthropic's own guidance is direct. The description must provide enough detail for Claude to know when to select the skill, while the rest of SKILL.md supplies implementation detail. The when is the load-bearing word. Implementation lives downstream.
Pushy descriptions fire. Polite ones don't.
Anthropic's skill-creator documentation warns that Claude has a tendency to undertrigger skills, defaulting to its own knowledge instead of consulting the SKILL.md [4]. The recommended fix is to write descriptions that are pushy on purpose.
Compare two descriptions for a hypothetical dashboard skill:
- "How to build a simple fast dashboard to display internal data" (polite, undertriggers)
- "How to build a simple fast dashboard to display internal data. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" (pushy, fires)
The second one is Anthropic's own pattern. It works because it names the surface where Claude pattern-matches and tells Claude to use the skill even when the trigger phrase is implicit.
Politeness is a failure mode.
The silent failure
A skill that produces bad output gets fixed. A skill that never loads gets forgotten. The asymmetry is the trap.
Engineering instincts run the other way. You write the SKILL.md, hand-test it with a slash command, see it work, ship. But hand-invocation bypasses the trigger. The slash command loads the skill in full. The auto-discovery path, where most production value lives, never gets exercised in testing.
The result is a graveyard of polished skills that work when called manually and fail to load in any other context. Anthropic itself ships a dedicated description-improver script alongside the skill-creator. The script splits an eval set into train and test prompts, runs each one three times to measure trigger rates, then iterates on the description until the rate climbs. The fact that this script exists at all is the tell. Description optimization is its own discipline.
What the body is for
Once the description earns the load, the body has one job: keep the loaded skill cheap. Progressive disclosure means bundled scripts execute without their code ever entering context, only their output. Reference files load on demand. A skill can package dozens of files and cost almost nothing per session, provided the SKILL.md body itself stays narrow enough to deserve its slot [5].
The body is not a dump. It is what Claude needs in working memory after selection has happened. Detailed protocols belong in linked reference files. Long examples belong in supporting files. SKILL.md itself is a router.
The maintenance asymmetry
User intent drifts. The phrasings your team used to describe a task in October are not the phrasings they use in May. New tooling enters the vocabulary. Old terms fade out of it.
The body of your skill ages well. The description ages fast. A description tuned for last quarter's language fails to fire on this quarter's requests, and the silent failure mode means no one catches the regression until someone notices Claude has stopped using the skill.
A maintenance rhythm that ignores this asymmetry rots. The fix is treating descriptions as living surfaces, reviewed on the same cadence as the workflows they govern, with trigger rates measured the same way an SRE measures error budgets.
Skills are an open standard now, adopted across Claude Code, OpenAI Codex CLI, Cursor, Gemini CLI, and GitHub Copilot. The mechanism that decides whether your skill loads is portable. The discipline that decides whether your description earns the load is not.
The description is the skill.