How to write a description that actually triggers
A description that reads clearly to you, who already knows what the skill does, is not the same thing as one that gives an agent enough to match a real request against. Before/after rewrites for the most common reason a skill silently never fires.
The gap: written for a reader who already knows
A description has to work for a reader who has never seen the skill before, because that is the position an agent is in on every single request. A description that summarizes the skill's purpose — what it is for, in the author's own mental model — tends to skip exactly the concrete trigger information a stranger, or an agent, would need.
Name the situations, not the purpose
Swap "what is this for" language for "when should this fire" language: the actual file types, commands, phrases, or situations that should invoke it. This is the single highest-leverage rewrite, because it is what a matching step actually has surface area to work with.
Length: enough for one concrete example, not more
Long enough to state the trigger situation and at least one concrete example phrase or file type; short enough to stay a single focused paragraph. If a description is trying to cover several unrelated capabilities, that is usually a sign the skill itself should split into two, not that the description needs trimming to fit.
Avoiding overlap with a sibling skill
Two skills can both mention "file" and "check" without truly competing for the same request. Two skills that both say "validate a configuration file for errors," with no further distinction, genuinely do. The fix is to narrow each description to what makes it different — the specific file type, the specific kind of check — not to reword either one in a way that still describes the same territory.
Common questions
Why doesn't my skill trigger even though the description sounds right to me?
The most common reason is a description that reads clearly to a human who already knows what the skill does, but gives an agent nothing concrete to match a real request against — no example phrasing, no named triggers, no distinctive vocabulary. A description has to work for a reader who has never seen the skill before, because that is the position the agent is in on every request.
What makes a trigger cue concrete instead of vague?
Naming the actual situations, file types, commands, or phrases that should invoke the skill, rather than describing its internal purpose. "Formats code" is vague; "formats Python files with black and isort when the user asks to format, lint-fix, or clean up a Python file" is concrete, because it gives the agent real surface area to match a request against.
How long should a description be?
Long enough to state the trigger situation and at least one concrete example phrase or file type, short enough to stay a single focused paragraph. A one-line description that is only the skill's name restated ("Handles PDF tasks") is almost always too short to give an agent anything to match; several unrelated capabilities crammed into one description is usually a sign the skill should be split rather than the description trimmed.
How do I know if my description overlaps a sibling skill?
Paste both SKILL.md files into a checker that compares descriptions for shared distinctive vocabulary, not just shared common words. Two skills can both mention "file" and "check" without truly competing; two skills that both say "validate a configuration file for errors" with no further distinction genuinely do compete for the same request, and the fix is to narrow each description to what makes it different, not just reword it.