You wrote a SKILL.md. It's in the right directory, named correctly, YAML frontmatter valid. You start a fresh session, send a request that's obviously in scope — and the agent does the task the old way, ignoring the skill entirely.
This isn't a loading bug. It's almost always the description.
The description is the only thing the agent reads to decide
Before an agent uses a skill, it has to choose it — and the only thing it's choosing against is one line of frontmatter. Not the procedure inside, not the examples, not the gates. The description. If that line doesn't match the shape of the request, the skill might as well not exist, no matter how good the rest of the file is.
This produces two distinct failure modes, and they look identical from the outside ("the skill isn't working") but have opposite fixes:
- The skill never fires. The description is too vague or too narrow to match real requests.
- The skill fires on everything. The description is too broad, and it's now competing with — and sometimes beating — skills that should have handled the request instead.
Topic-shaped vs. trigger-shaped
The single most common mistake is writing a description that names the subject instead of the situation:
"Helps with debugging."
That's topic-shaped. It tells you what the skill is about, but gives the agent nothing to match against — no situation, no timing, no boundary. Compare:
"Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes."
That's trigger-shaped. It names the situation ("encountering a bug"), the timing ("before proposing fixes"), and implicitly the boundary (not for feature requests, not for style questions). An agent scanning descriptions can actually decide from this one.
The pattern generalizes: "Use when [situation]" beats "Helps with [topic]" almost every time.
Write the words the user would actually type
Matching happens against the incoming request's phrasing, not your internal naming for the skill. If you call it "the verification skill" internally but nobody types "verification," write the description with the words people actually use — "check," "confirm," "make sure this is done," whatever your users' real phrasing is. A skill named with jargon only you understand is functionally invisible.
Keep it to one or two sentences — and make them earn it
Longer descriptions get skimmed; shorter ones fail to distinguish the skill from its neighbors. Aim for one or two sentences that fully specify: what situation triggers this, and (if it matters) what it explicitly doesn't cover.
Watch for overlap, not just vagueness
Even a well-written, specific description can fail if it overlaps with another skill's trigger. When two skills could both plausibly match a request, the agent burns judgment choosing between them — and sometimes chooses wrong. If you have two skills firing on the same kind of request, that's not two useful skills, it's one skill with a coin flip attached. Narrow the descriptions until only one can apply to any given request.
The fast diagnostic
Before you touch the procedure, the gates, or anything else in the file, ask: if I paste this description next to five other things this agent might do, does it obviously match only the cases I want it to match? If you're not sure, neither is the agent — and "not sure" resolves to "doesn't fire" more often than you'd expect.
Full write-up (with a worked before/after example): https://agentkitworks.com/answers/how-to-write-skill-description
