Claude Code Skill Not Triggering? Every Cause and the Fix (2026)

You wrote a Claude Code skill (or installed one from a community repo). The YAML looks right, the folder is where the docs say it should go, and Claude acts like it doesn't exist. No error, no warning, nothing in the output that even hints a skill was considered and rejected.

That silence is the whole problem. Skills fail invisibly, so fixing one means checking causes in the right order instead of guessing. This guide covers every known reason a Claude Code skill won't trigger, from the obvious to the one almost nobody knows about, in the order you should actually check them.

If you just want the checklist, here it is. Work down this list in order, since each cause is more subtle than the last, and later ones only matter once the earlier ones are ruled out.

Before fixing anything, it helps to know what happens under the hood, because every cause below traces back to one of two steps breaking.

At session startup, Claude Code scans your skill directories (both the personal ~/.claude/skills/ directory and any project-level .claude/skills/ directory) and builds a lightweight index containing only each skill's name and description, pulled from the YAML frontmatter at the top of SKILL.md. That index gets injected into the system prompt as part of the same character budget that also holds your slash command list. The full body of SKILL.md, the instructions, the examples, the reference files, never loads at this stage.

Then, when you send a prompt, Claude compares your request against that list of descriptions. If your wording matches a description closely enough, Claude decides to invoke the skill, and only then does the full SKILL.md content load into context for that turn. If nothing matches, nothing loads, and Claude proceeds as if the skill were never installed.

Skills load once, at startup. If you added a skill, edited an existing one, or installed a plugin bundle while a session was already running, Claude is working from the index it built when the session began and has no idea the new skill exists.

Exit and start a fresh session, or run /reload-plugins on recent Claude Code builds to rescan without a full restart. Check this first. It's the fastest thing on this list to rule out, and it silently explains a large share of "my skill isn't working" reports that turn out to have nothing wrong with the skill itself.

Personal skills live at ~/.claude/skills/skill-name/SKILL.md. Project skills live at .claude/skills/skill-name/SKILL.md inside the repo. The file must be named SKILL.md exactly, capitalization included.

The classic mistake comes from unzipping a downloaded skill. Most zip tools preserve the top-level folder from the archive, so unzipping skill-name.zip into ~/.claude/skills/ often produces ~/.claude/skills/skill-name/skill-name/SKILL.md, one folder too deep. Claude Code's scanner looks exactly one level down from the skills directory, so that extra nesting means it never finds the file at all, and there's no error to tell you why.

If your skill's name doesn't show up in that output, the path is the problem, and everything else in this guide is irrelevant until it's fixed. Move the inner folder's contents up one level so SKILL.md sits directly under skill-name/.

Invalid frontmatter fails silently, the same way an invalid path does. The two usual suspects are the opening or closing --- delimiters being missing or indented, and an unquoted colon appearing inside the description string, which breaks YAML's own parsing rules before Claude Code ever sees the value.

A quick sanity check that doesn't require reading YAML by eye: ask Claude directly, in a running session, which skills it currently has loaded. If your skill is missing from the answer but you already confirmed the path is correct with the ls command above, broken frontmatter is almost always why. Run the file through any YAML validator, or just paste the frontmatter block into Claude and ask if it parses.

This is the big one once loading is confirmed, and it's the cause most people never think to question because the skill "looks fine" when they read it. Claude matches your request against the description text specifically, not the skill's title, not its body, not its examples. A description like "helps with code quality" will basically never fire, because no prompt a real developer types resembles that phrase.

Write the description to contain the actual words you type when you want the skill to run. If you say "review this PR", the description needs to contain "review" and "PR", not an abstraction like "code quality analysis".

The directive pattern works because it does two things at once: it states the exact trigger condition in language close to how people actually phrase requests, and it tells Claude what not to do instead (write the config directly) if the skill isn't invoked. That negative constraint matters more than it looks like it should, since it removes the easy fallback Claude would otherwise take.

This is the failure mode that catches heavy skill users, and the one almost no documentation mentions. The system prompt list built at startup, containing every skill's name and description plus every slash command definition, has a size cap: 15,000 characters by default as of Claude Code 2.0.70, roughly 4,000 tokens.

Install enough skills, or a handful with long descriptions, and skills past that cap simply don't make it into the list. No warning is shown anywhere in the CLI. Since Claude Code's own instructions tell the model not to use a skill that isn't listed, those skills are functionally gone for the session, even though the files on disk are completely correct.

If a skill that used to work stopped firing right after you installed several new ones, or added a plugin bundle with its own skill set, this budget is almost certainly the reason. It's a shared pool: every project skill, every personal skill, and every slash command all draw from the same 15,000 characters, and whichever ones got indexed first (or happen to sort earlier) survive at the expense of whatever pushed the total over the limit.

Raising the environment variable is the fast fix. The better long-term fix is pruning: uninstall skills you don't actively use, and keep every description tight. A focused, 200 to 250 character description that front-loads the actual trigger phrases costs far less of the shared budget than a paragraph-length description written like marketing copy, and it activates more reliably too, since Cause 4 rewards concise, specific wording anyway.

If you've confirmed the session is fresh, the path is correct, the frontmatter parses, the description is specific, and you're under the character budget, three narrower causes are left.

One diagnostic separates these two failure classes cleanly: invoke the skill manually with /skill-name. If manual invocation works but automatic triggering doesn't, the description is your problem (Cause 4) or you've hit the character budget (Cause 5). If manual invocation fails too, go back to the path and frontmatter checks (Causes 2 and 3), since the skill isn't loading at all.

The same discipline that keeps skills reliable also matters for parallel agent workflows. If you're running several Claude Code sessions at once across Git worktrees, each session builds its own independent skill index at startup, so a skill fixed in one worktree's session won't retroactively fix an already-running session in another. For a broader command and shortcut reference while you're debugging, the Claude Code cheatsheet covers the surrounding CLI surface this guide doesn't.