How to write a skill description Claude will actually use
The description line is the most important part of a skill. A vague one means the skill sits unused. A description that is too broad means it loads when you do not want it. This guide covers what the documentation says and some practical habits for writing a good one.
What the description does
Claude sees the name and description of each available skill. When a request matches a description, Claude loads the full SKILL.md. If you leave the description out, Claude Code uses the first non-empty line of the skill's content instead, which is rarely what you want.
The documentation also describes an optional when_to_use field for extra trigger context, such as phrases or example requests. It is added to the description. Together they are cut off at 1,536 characters in the skill listing, so put the most important words first.
Say what it does and when to use it
A good description has two parts: what the skill produces, and the situations where it applies. Compare these two.
- Weak: Helps with blog posts.
- Stronger: Drafts a blog post outline from a topic and target reader. Use when the user asks for an outline, a content plan or a post structure.
The weak version does not say what you get back or when to reach for it, so Claude has little to match against.
Use the words people actually type
Think about how you would ask for this job in a hurry. If you would say "plan my posts for the week," that phrase belongs in the description or in when_to_use. This is our practical advice rather than a rule from the documentation, but it follows from how matching works: the closer the description is to your real requests, the more likely it is to be picked.
Keep one job per skill
A skill that tries to outline posts, write them, optimize them and publish them is hard to describe in a few sentences, and a long mixed description tends to match too many requests. Splitting it into smaller skills makes each description clearer. Again, this is a working habit rather than a documented requirement.
Control when a skill runs
The documentation lists several frontmatter settings that change how a skill is used.
- disable-model-invocation: true stops Claude from loading the skill automatically. You run it yourself with a slash command.
- user-invocable: false hides the skill from the slash menu so only Claude can invoke it.
- paths takes glob patterns that limit when Claude loads the skill automatically.
Use the first one for anything with side effects that you only want to run on purpose.
Test it before you rely on it
- Ask for the job in plain words, without naming the skill, and see whether Claude loads it.
- Try a nearby request that should not use the skill and check that it stays out of the way.
- If it misfires, change the wording of the description and try again.
- Run the skill with its slash command to check the instructions separately from the matching.
Last checked against Anthropic's Claude Code documentation on October 13, 2026. Features change, so confirm details in the current documentation.
This guide is for general information only and is not a promise of any result. See our disclaimer. Questions or corrections? Contact us.