Why your Claude Code skill does not fire, and how to tell
A skill that works when you name it and ignores you otherwise has a description problem, not a logic problem. How to find out which, in about ten minutes.
You wrote the skill, you tested it, it worked. A week later you ask for the thing it does and get a generic answer instead. Nothing changed in the file. Most people conclude the skill is broken and start rewriting the body, which is the one part that was never involved.
Only one line decides whether a skill is considered
A skill folder has a SKILL.md with frontmatter at the top. The description field in that frontmatter is what Claude reads when deciding whether the skill is relevant to what you just asked. The body is not read at that point. It is loaded afterwards, once the skill has already been selected.
So a skill that does not fire has almost always failed at one line of text, and you can prove that in a minute: name the skill directly in your prompt. If it does the job correctly when named and ignores you when not, the body is fine and the description is the whole problem.
Descriptions written for humans do not match
The usual failure is a description written the way you would introduce the skill to a colleague. It reads well and it matches nothing:
description: A helpful assistant for working with your projectThere is nothing in that sentence a real prompt would contain. Compare it against what someone actually types, which is concrete and full of the nouns of the job:
description: Checks changed files against the rules in docs/house-rules.md.
Use when asked to review, check conventions, or look for rule violations.The second one names the artefact, the file, and three phrasings someone would use. It is less elegant and it matches.
The four descriptions that fail
| The description | Why it misses |
|---|---|
| Abstract praise: a powerful helper for X | Contains no word a prompt would contain |
| The tool's name only: tfsec wrapper | Nobody asks for the tool, they ask for the outcome |
| Everything at once: helps with code, docs, tests, and review | Fires constantly, which is a worse failure than never |
| Internal jargon: runs the Tier-2 gate | Only matches if the reader already knows your vocabulary |
Find out in ten minutes instead of guessing
Write the prompts down before you change anything. Ten that should fire the skill, ten that should not. Phrase them the way you would actually type them, including the sloppy ones, because the sloppy ones are what you will type at five o'clock.
- Write ten prompts that should fire it, in your own words, not the description's words.
- Write ten that should not, including near-misses in the same subject area.
- Run all twenty against the skill as it is now. Record what happened.
- Rewrite the description using the nouns from the prompts that failed.
- Run the same twenty again. The second number is only meaningful next to the first.
The half that should not fire is the half people skip, and it is the half that catches a description so broad the skill fires on everything.
What a good result looks like
You are not aiming for twenty out of twenty. A skill that fires on every near-miss has a description that is too greedy, and it will start intercepting work it cannot do. What you want is high on the should-fire half, near zero on the should-not half, and a written record of which prompts moved.
Keep the file. It is the only way to know whether your next edit helped, and it is the thing that turns feels better into a number. If you want the shape of one, every skill we sell ships its suite and we publish the before and after.
Questions
Why does my skill only work when I name it directly?
Naming it loads it explicitly, which bypasses matching entirely. If it works that way and not otherwise, the skill itself is fine and its description is what failed. The description is the only thing Claude reads when deciding whether a skill is relevant.
Does the length of SKILL.md affect whether it triggers?
Not directly. Matching happens on the frontmatter description, not the body. Length matters for a different reason: a long body is loaded into context every turn once the skill is active, which costs you room for the actual work.
How many test prompts do I need to be confident?
Twenty or so, split between prompts that should fire it and prompts that should not. The second half is what catches a description so broad that the skill fires on everything, which is a worse failure than not firing at all.
Keep reading
Or skip the afternoonand drop one in.
Every skill in the catalogue is a folder you drag into your skills directory. Tested on a clean machine, documented, with the trigger accuracy published.