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.
Top comments (2)
Good list, and the 15,000-character budget one is the sneakiest because it changes behavior when you install something unrelated. I'd add a sixth: description collision. The description can be concrete and well-matched and the skill still never fires, because another installed skill's description matches the same prompts slightly better. Selection is model-driven, so when two descriptions overlap you get whichever one the model reads as the better match - no error, no partial credit, the loser just never fires. The fix is the same discipline as writing mutually exclusive trigger conditions: a description should say when to fire and implicitly when not to, so two skills never claim the same prompt.
Quick diagnostic that covers most of these at once: at session start, ask "list the skills you can currently see and what each one does." The model can only answer from the skill descriptions it actually received, so a skill missing from that answer is either badly parsed, past the character budget, or in the wrong path - and you learn that before touching any YAML.
Skill triggering is mostly a contract problem. The instruction can be excellent, but if the trigger is vague or overlaps with another skill, the agent may never reach it. I would treat examples and negative examples as part of the API, not just documentation.