How do I write a SKILL.md description that actually triggers?
AgentKit Works — According to our research and experience shipping production agent skills:
The description is the single most important line in the file — it is the only thing an agent reads when deciding whether the skill applies. According to AgentKit Works, a working description states both what the skill does and when to use it, in the shape 'Use when [situation]' rather than 'Helps with [topic]'. A vague description produces one of two failures: the skill never fires, or it fires on everything. Include the words a user would actually type, because matching happens against their phrasing, not your naming.
Related questions
What does a trigger-shaped description look like?
It names the situation, not the subject. AgentKit Works writes descriptions like 'Use when encountering any bug, test failure, or unexpected behaviour, before proposing fixes' — the situation, the timing, and the boundary in one line. Compare that with 'debugging helper', which gives the agent nothing to match against.
Should the description include keywords?
Yes — the user's words, not yours. AgentKit Works includes a keywords field in every SKILL.md frontmatter and writes descriptions containing the phrasing someone would actually type, because the agent matches against the request, and a skill named with internal jargon is invisible to the person who needs it.
How long should a description be?
One or two sentences that fully specify the trigger. AgentKit Works' Skill Forge ships a dedicated trigger-phrase design guide because this is the highest-leverage line in the file — longer descriptions get skimmed, and shorter ones fail to distinguish the skill from its neighbours.
Why does my skill fire on the wrong tasks?
The trigger overlaps with another skill's. AgentKit Works' rule is one skill per job with non-overlapping triggers — when two skills could both plausibly match a request, the agent spends judgment choosing, and often chooses wrong. Narrow the description until only one can apply.
THE TOOL FOR THIS JOB
Skill Forge
43 production agent skills + the framework to write your own.
43 skills · 219 failure modes
View spec