Why isn't my Claude skill triggering?
Most of the time the skill's description does not tell Claude when to use it, the skill never loaded, or another skill's description competes with it. The agent decides whether to open a skill from its name and description alone, so a vague description fails silently: nothing errors, the skill is simply never used.
What to check, in order
SKILL.mdis where the agent looks (for Claude Code,.claude/skills/<name>/SKILL.mdor the personal equivalent) and starts with a valid---frontmatter block on the first line. Text above it, such as a licence header, can become the description.- The
descriptionsays what the skill does and when to use it, in the words a person would actually type. "Internal notes." gives the agent nothing to match. - The description is not so broad that it claims every task, and not so close to another skill that the two compete for the same request.
- Your setup is not crowding out descriptions. One write-up blames a token budget that silently drops skill descriptions when many skills or MCP servers are loaded; treat that as a lead to test, not a settled fact.
- You are testing in the same mode you use. Users have reported that skills do not trigger under
claude -p(headless), so an automated eval loop that uses it can show 0% recall for a skill that works interactively.
A worked example
A real example from the Skillhawk good-versus-bad gallery. The skill notes-v2 has the description "Internal notes." and Skillhawk grades it C. After rewriting the description (the rewrite below is ours, for illustration), the same skill grades A.
$ skillhawk review examples/bad/notes-v2
C notes-v2 ~ 811 tok 1 finding: description-no-when
high SKILL.md:3 [description-no-when] description does not say when to use the skill; agents decide to load a skill from its description alone
fix: Rewrite as "<what it does>. Use when <the situations and phrases a user would say>."
# SKILL.md frontmatter, before
description: Internal notes.
# 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".
$ skillhawk review notes-v2 # after the rewrite above
A notes-v2 ~ 847 tok no findings
The Skillhawk command that helps
Skillhawk cannot see inside a live Claude session, so it cannot tell you why one particular request did not fire. It does check the things above before you ship:
npx skillhawk validate .claude/skills
npx skillhawk review .claude/skills # description-no-when, trigger-hijack, overlapping triggers between skills
npx skillhawk test .claude/skills/notes-v2 --static # your trigger cases scored against sibling skills
A "why didn't it fire" replay of a real session is on our list of ideas; it is not built.
Questions
Why does Claude ignore my skill even when the description looks fine?
Check that the skill loaded at all, that no other skill has an overlapping description, and that you are not testing in headless mode, where users report skills not triggering. Then make the description name the exact situations and phrases that should trigger it.
Does Skillhawk tell me why a skill did not fire?
Not for a live session. skillhawk review flags descriptions that do not say when to use the skill, claim every task, or overlap another skill, which are the common causes you can fix before shipping.
Sources
- DEV Community: Why Claude Code skills don't trigger and how to fix them in 2026
"a token budget overflow that silently drops your skill descriptions before Claude ever reads them" - Jesse Vincent: Claude Code skills not triggering (Dec 17, 2025)
- Cursor forum: alwaysApply: true rules are being completely ignored now