Claude Code Skill Not Triggering? Here Are the 5 Actual Causes

You drop a skill into `~/.claude/skills/`, check the YAML, start a session, and prompt Claude with something directly related to what the skill does. You get a generic response. No error. No hint that a skill existed and wasn't a match. Just silence, as if the file isn't there.

Here's why that happens. At session startup, Claude Code scans your skill directories and builds an index containing only each skill's name and description from the YAML frontmatter. That index gets injected into the system prompt. The full body of `SKILL.md` never loads at startup. It only loads if Claude decides the description closely matches your prompt.

Which means the description is the trigger, not documentation. A vague description like "helps with code quality" will never match a real developer prompt, regardless of how detailed the skill body is. But that's only one of five causes, and it's not even where to start.

The full list, in the order you should actually check them:

• **Session not restarted** after adding or editing the skill (skills load once at startup)
• **Wrong path or double-nested folder** from unzipping a downloaded skill
• **Broken YAML frontmatter**, usually an unquoted colon in the description field that fails to parse silently
• **Description too vague or abstract** to match how you actually prompt
• **Character budget exceeded**, where Claude Code silently drops skills past a 15,000 character default cap with no warning anywhere in the CLI

That last one catches a lot of heavy skill users. Install enough skills (or a plugin bundle) and older ones disappear from Claude's awareness with nothing in the output to tell you it happened.

I covered each cause with exact commands, YAML examples, and activation rate data from community testing here: https://devencyclopedia.com/blog/claude-code-skill-not-triggering-fix

The description section includes a side-by-side comparison of weak, concrete, and directive-style wording, with observed activation rates. The difference between "Docker expert for containerization" and a directive-style description was almost 25 percentage points in testing.