Your skill’s description is the single most important field in SKILL.md. The model reads only the name + description when it decides whether to invoke a skill. The body of the file is loaded only after that decision is made. So if the description is vague, generic, or written like marketing copy, the skill will sit in your repo never getting picked up — no matter how good the implementation behind it is.
This guide gives you the patterns that consistently fire, the traps to avoid, and a checklist you can run any description against in under a minute.
What “trigger reliably” actually means
When the agent decides which skill to invoke, it’s doing a routing decision over a list of {name, description} pairs. The description has to do three jobs at once:
- Tell the model what task this skill is for (the goal)
- List concrete trigger phrases the user is likely to say
- Disambiguate from nearby skills that could plausibly fire on the same request
Heuristic. Read your description out loud. If it sounds like the back of a software box, rewrite it. If it sounds like a runbook (“use this whenever the user mentions X, Y, or Z”), you’re on track.
The pattern that works
Almost every well-triggering skill description follows the same skeleton:
Use this skill whenever {triggering condition}. This includes:
{specific trigger A}, {specific trigger B}, {specific trigger C}.
Trigger especially when the user mentions {literal phrases / file
extensions}. Do NOT use when {clear edge case}.The four parts in plain English:
- “Use this skill whenever” — frames it as a routing rule, not a feature description
- “This includes…” — concrete jobs (verbs + objects), not abstract capabilities
- “Trigger especially when…” — literal phrases or file types that should match
- “Do NOT use when…” — at least one negative example, to keep it from over-firing
Before / after
Before
description: A powerful PDF utility supporting extraction, merging,
splitting, form filling, and OCR.Reads like a product page. The model has nothing to match a user request against.
After
description: Use this skill whenever a PDF file is involved — reading
or extracting text, combining or merging multiple PDFs, splitting a
PDF apart, rotating pages, adding watermarks, filling PDF forms,
encrypting/decrypting, or running OCR on scanned PDFs. Trigger when
the user mentions a .pdf file or asks to produce one. Do NOT use
for Word documents or images.Now the model has eight concrete triggers, two literal phrases (.pdf, “produce one”), and one disambiguation.
Four traps to avoid
1. Marketing copy
“Best-in-class”, “powerful”, “comprehensive” — none of these are routing signals. Cut them.
2. Capability lists without verbs
“Supports PDF, DOCX, XLSX” tells the model what file types are in scope but not what jobs to do with them. Always pair the noun with a verb: “extract text from PDFs”, “merge PDFs”, “fill PDF forms”.
3. Overly broad triggers
A description like “Use whenever the user wants to do anything with files” will fire on almost everything. Narrow it. If the skill is genuinely broad, split it into sub-skills with sharper descriptions.
4. No negative examples
If two skills could plausibly fire on the same request, both descriptions should explicitly disclaim the other (“Do NOT use this when…”). One sentence prevents a lot of misfires.
Test it. Take three real user phrases that should trigger your skill and three that shouldn’t. Run them against the agent. If the hit rate isn’t 6/6, the description needs another pass.
The 60-second checklist
- Starts with “Use this skill when…” or “Use this skill whenever…”
- Names at least three concrete jobs (verb + object)
- Names at least one literal trigger (file extension, phrase, verb)
- Names at least one negative example (“Do NOT use…”)
- No marketing adjectives (“powerful”, “best”, “comprehensive”)
- Under ~120 words — anything longer is body content, not routing signal
Related
For the broader picture of where description sits in the file, see Anatomy of a Skill. For the routing mechanics that read it, see How skill triggers work.