Debugging Claude Skills That Refuse to Trigger
You wrote the skill, you installed it, you typed the exact request it was built for, and Claude answered from general knowledge as if the skill did not exist. This is the most common skill failure and the most fixable one, because non-triggering has a short list of causes and each has a distinct symptom. This post is the diagnostic sequence: run it top to bottom and you will find the fault.
Background on how triggering works lives in how skill triggers work; this post assumes the basics and focuses on what to do when they fail.
TL;DR: Debug in this order. First confirm the skill is actually installed and loadable: right directory, folder present, and valid YAML front-matter, because a single stray colon can stop a skill loading with no visible error. Second, test whether the skill can fire at all by asking for it by name; if a direct request works but natural phrasing does not, the fault is the description, not the install. Third, diagnose the description: it must contain the words users actually type, state when to use the skill rather than just what it does, and avoid vague nouns. Fourth, check for sibling interference, since another installed skill with an overlapping description can win the trigger decision inconsistently. Fifth, verify in a genuinely cold session, because a session where you have been discussing the skill will trigger it for reasons that will not survive contact with a fresh conversation. Change one variable at a time and re-test after each.
Step 1: Is the skill even loaded?
Rule out the boring failures first; they cause half of all cases.
Check the location. The skill folder must sit in the directory the environment reads skills from, and the folder must directly contain the SKILL.md, not a nested copy:
skills/
meeting-summariser/
SKILL.md <- correct
skills/
meeting-summariser/
meeting-summariser/
SKILL.md <- one level too deep; a common unzip artefact
The double-nesting mistake is the classic result of unzipping a shared skill into a folder of the same name.
Check the listing. If the environment offers a way to list installed skills, confirm yours appears in it. Present in the folder but absent from the listing points to the next check.
Validate the YAML. Malformed front-matter can prevent a skill loading silently. Run the front-matter through a YAML parser:
python -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1]); print('OK')"
The usual culprits: an unquoted colon inside the description, tabs instead of spaces, smart quotes pasted from a word processor, or a missing closing --- fence. Fix, reload, re-test.
Step 2: Can it fire at all? The by-name test
In a fresh session, ask for the skill explicitly: "use the meeting-summariser skill on this transcript". Two outcomes, two diagnoses:
- It fires by name but not naturally. The install is fine; the description is the fault. Go to Step 3, which is where most debugging sessions end up.
- It does not fire even by name. The skill is not loading. Return to Step 1; you missed something, most often the path or the YAML.
This single test cleanly splits the problem space, which is why it comes before any description surgery.
Step 3: Diagnose the description
The description is the only evidence Claude has when deciding whether to load your skill. Read yours and ask three questions.
Does it contain the words you actually typed? Write down the exact request that failed, then look for its key nouns and verbs in the description. The most common mismatch is vocabulary drift: the description says "transcripts" while you asked about a "call recording"; it says "summarise" while you asked to "write up".
# Failed to trigger on "write up yesterday's call"
description: Summarises meeting transcripts into structured notes.
# Fixed: covers the vocabulary users actually use
description: Summarises meetings from transcripts or call recordings into decisions, actions, and owners. Use when the user asks to summarise, write up, or take notes on a meeting, call, or standup.
Does it say when, not just what? A description that only describes capability ("A skill for working with meetings") gives no signal about which requests should invoke it. The "Use when..." sentence is not decoration; it is the trigger.
Is it hiding behind vague nouns? "Helps with documents", "assists with content", "handles data tasks" trigger on nothing because they claim everything. Specific and narrow beats broad and hopeful, every time.
Rewrite, reload, and re-run the exact failing prompt. One change at a time: if you rewrite the whole description and it works, you have learned nothing about which words mattered.
Step 4: Check for sibling interference
If the description looks right and the by-name test passes, look sideways. Triggering is a competition among every installed skill; another skill claiming the same vocabulary can win inconsistently.
The test: temporarily move suspect siblings out of the skills directory and re-run the failing prompt. If the skill now fires, you have an overlap conflict, and the fix is differentiation, not removal: sharpen both descriptions so each owns its own words, including an explicit "not for X" clause on the boundary. Library-wide overlap management is covered in organising a skill library that scales.
A related interference case: the request genuinely matches two of your skills because it spans a workflow, in which case the answer may be composition rather than competition; see skill chaining.
Step 5: Verify in a cold session, then lock it in
Skills that trigger in your testing session and fail for everyone else usually share one cause: the test session was warm. If you have been editing and discussing the skill in the same conversation, Claude has the skill's content in context and will use it regardless of the description. That success is fake.
The verification protocol:
- Open a completely fresh session.
- Type the natural request, with no mention of skills.
- Confirm the skill fires and the output follows its instructions.
- Run one negative case: a nearby-but-different request that should not fire it.
- Add both prompts to your permanent eval set per the testing and eval guide, so the next description edit cannot silently reintroduce the bug.
The full diagnostic table
| Symptom | Likely cause | Fix |
|---|---|---|
| Absent from skill listing | Wrong directory or double-nested folder | Correct the path; check for unzip nesting |
| In folder, still never fires, even by name | Malformed YAML front-matter | Validate and repair the YAML |
| Fires by name, not naturally | Description lacks user vocabulary or a "use when" clause | Rewrite description with real trigger phrases |
| Fires sometimes, inconsistently | Overlapping sibling skill | Differentiate both descriptions |
| Fires in your session, not for others | Warm-session false positive | Re-verify cold; fix description as needed |
| Fires but ignores its own instructions | Body problem, not a trigger problem | See writing a skill from scratch for body structure |
| Broke after an update | Description edit changed trigger surface | Diff the description; re-run the eval set |
That last row is worth internalising: trigger regressions are a normal cost of editing descriptions, which is why versioned releases and re-testing on every bump matter even for small changes.
Frequently asked questions
Why does my skill trigger for some phrasings and not others?
Because triggering matches your description against the request, and your description only covers some of the vocabulary. Collect the phrasings that fail and fold their key words into the description as synonyms.
Can I force a skill to always load?
Naming it explicitly in the request is the reliable manual override. For automatic behaviour, the description is the mechanism; there is no supported always-on flag for ordinary skills.
The skill triggers but does the wrong thing. Same debugging process?
No, that is a body problem, not a trigger problem. Triggering got the instructions loaded; if they are then misapplied, the fix is clearer structure, explicit steps, and examples in the body, which is authoring territory rather than trigger debugging.
About the author
Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.
Next step: Prevent the next trigger bug at design time with how skill triggers work, or explore 1,000+ AI tools at yanni.uk/ai-tools.
Sources
- Claude documentation (agent skills): https://docs.claude.com
- Anthropic: https://www.anthropic.com