How to write a SKILL.md description that triggers
Write the description as what the skill does, then when to use it, in the words a person would actually type: "<what it does>. Use when <the situations and phrases>." Keep it under 1024 characters, scope it to one job, and put detail in the body, because the agent decides whether to open the skill from the description alone.
Rules that hold up
- Say the "when" explicitly. "Use when the user asks for a recap" beats a topic label.
- Use the user's vocabulary: the phrases they would type, not your internal name for the thing.
- One job per skill. A description that claims every task crowds out the skills that should fire.
- Do not overlap a neighbour. If two descriptions would fire on the same request, merge them or separate the "when".
- Stay under 1024 characters (the Agent Skills limit). Move detail into the body or
references/. - Re-test after editing. Descriptions regress quietly when someone shortens them.
A worked example
The same skill before and after (the rewrite is ours; the review lines are real Skillhawk output on the notes-v2 example):
# before
description: Internal notes.
C notes-v2 ~ 811 tok 1 finding: description-no-when
# after
description: Formats meeting notes into the team template with decisions and owners. Use when the user pastes meeting notes, asks for a recap, or says "write up the notes".
A notes-v2 ~ 847 tok no findings
The Skillhawk command that helps
These check the description before you ship:
npx skillhawk review <skill-dir> # description-no-when, description-length, trigger-hijack
npx skillhawk test <skill-dir> --static # trigger cases (tests/cases.yaml) scored against sibling skills
Passing a static check does not guarantee the model will pick the skill in a real session; it removes the common mistakes.
Questions
How long can a SKILL.md description be?
The Agent Skills format limits it to 1024 characters, and Skillhawk flags longer ones. Shorter and specific usually works better than long.
What should a skill description contain?
What the skill does and when to use it, using the words a person would type, scoped to one job.
Sources
- DEV Community: Why Claude Code skills don't trigger and how to fix them in 2026
- Jesse Vincent: Claude Code skills not triggering (Dec 17, 2025)