Skill Description

Skill description is the single most important line in a Claude Skill. It lives in the YAML frontmatter of SKILL.md and tells the model whether the current request matches the intended task. Anthropic made this the decision engine on purpose. A sharp description loads the Skill at exactly the right moment. A vague one leaves it on the shelf forever.

It is not the full instruction set. That lives in the body below the frontmatter. It is not a marketing headline either. The description exists solely for the model to parse against user requests. Write it for the machine first then tune for humans.

Designers new to Skills often stuff the description with every possible synonym. The model gets confused and either never triggers or loads on unrelated work. Others make it too narrow and the Skill becomes invisible. The sweet spot is specific enough to avoid false positives yet broad enough to catch real use cases.

We wrote the description for our UX critique Skill as Audits any flow or screen against Nielsen heuristics plus our three custom rules. Use on critique review or red team requests. It fires perfectly on real flows and stays silent during copy tasks or brand reviews. The team stopped writing ad hoc critique prompts entirely.

A fintech client used description: Checks microcopy against brand voice guide for tone redundancy jargon and accessibility. Triggers on proofread review copy or check microcopy. Their QA time dropped by sixty percent. False triggers disappeared after we removed one overlapping word from the description.

Craft a skill description when you want predictable automatic loading. Spend thirty minutes testing it against twenty real prompts. Refine until it hits every intended case and misses the borderline ones. Never use it for Skills that try to do two jobs at once.

Avoid long descriptions that waste tokens before the real instructions load. Keep them under fifty words. Prioritize trigger phrases the team actually types in chat. Test against the five starter tasks every design team repeats.

The description determines whether your library feels magical or broken. Teams that obsess over it end up with reliable tools. Teams that treat it as an afterthought watch their Skills collect digital dust.

Update the description when usage data shows missed triggers or unwanted loads. The change propagates on the next Git pull. No redeploy. No manifest file. Just one edited line.

A great skill description makes the model feel like it finally understands how your team actually works.

Skill descriptions turn vague AI requests into predictable loaded behaviors.