Writing Descriptions That Trigger Reliably
The Description Is the Whole Game
A skill only helps if Claude actually uses it at the right moment — and that decision rests almost entirely on the description. Claude matches your request against descriptions semantically, so the language in the description has to overlap with how you (and your team) actually phrase requests. A perfect skill body is useless if the description never triggers it.
A good description answers two questions
(1) What does the skill DO? (2) WHEN should Claude use it? If someone told you 'your job is to help with docs,' you wouldn't know what to do — and Claude thinks the same way. Be explicit about both the action and the trigger conditions.
Vague vs. Specific
The difference between a skill that triggers and one that sits unused is usually specificity. Compare a vague description against one packed with the words a user would actually say:
| Vague (often misses) | Specific (triggers reliably) |
|---|---|
| 'Helps with PRs' | 'Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing changes for a pull request.' |
| 'Code review' | 'Reviews code for quality and security. Use when reviewing a PR, checking a diff, or before merging.' |
| 'Performance stuff' | 'Profiles and optimizes slow code. Use when code is slow, when profiling, or when the user asks to make something faster.' |
Specific descriptions name the action AND echo the phrases users actually type — that overlap is what triggers the match.
Add the Phrases You Actually Say
If a skill isn't triggering when you expect, the fix is almost always to add keywords that match how you really phrase requests. Test with variations and fold any that fail into the description.
Test the phrasings you'd actually use; add the keywords from any that fail to match so all of them trigger the skill.
When It Triggers Too Often
The opposite problem is over-triggering — Claude reaching for a skill when you didn't want it. Two fixes: make the description MORE specific (narrow the trigger conditions), or, if it should only ever run on demand, set disable-model-invocation: true so only you can invoke it.
- 1.Not triggering? Add trigger phrases that match how you actually ask, and test variations.
- 2.Wrong skill triggering? Your descriptions are too similar — make each one distinct.
- 3.Triggering too often? Tighten the description, or add disable-model-invocation: true for manual-only.
- 4.Use when_to_use to add example requests and trigger phrases without bloating the main description.
Next
Descriptions control WHEN a skill runs. The next lesson covers what it can DO while active — pre-approving tools with allowed-tools and controlling who can invoke it.
Key Takeaways
- ✓Claude matches requests to skills semantically on the description, so a skill only triggers if its description overlaps with how you phrase requests.
- ✓A good description answers two questions: what the skill DOES and WHEN Claude should use it.
- ✓Specific descriptions that echo the phrases users actually type trigger far more reliably than vague ones.
- ✓If a skill isn't triggering, add the keywords from the phrasings you actually use; test variations and fold in any that fail.
- ✓If a skill triggers too often, make the description more specific or set disable-model-invocation: true for manual-only.
- ✓If the WRONG skill triggers, your descriptions are too similar — make each distinct; use when_to_use for extra trigger phrases.
Check Your Understanding
Test what you learned in this lesson.
Q1.What two questions should a good skill description answer?
Q2.Your skill exists but Claude never uses it when expected. What's the most likely fix?
Q3.A skill triggers too often, even when you don't want it. What can you do?
Q4.Claude keeps using the WRONG skill among several similar ones. Why?
Practice This Lesson