Skip to content
RuleSellBeta
Sign up

Topic · A1

Your Claude Skill Isn't Triggering. Here Are the 8 Reasons.

Eight specific causes — symptom, diagnosis, fix — for the most common Claude Code skill failure mode. Based on Obra's December 2025 debugging post and confirmed against GitHub issue #11266.

# Your Claude Skill Isn't Triggering. Here Are the 8 Reasons. You wrote a skill. It looks fine. It doesn't fire. Below are the eight specific causes, in descending order of how often we see them — and the diagnosis + fix for each. This is the playbook Obra published in December 2025 (blog.fsck.com), confirmed against Claude Code issue #11266 and our own audit of 100 community skills. If you've checked all eight and it still doesn't trigger, it's almost certainly a ninth thing we don't know about — open an issue.

Cause 1: The description is vague

Symptom. Claude never picks the skill, no matter what you prompt. /skill-name works (so it's loaded), but auto-invocation never happens. Diagnosis. Read your description field. If it could describe any skill in the same category — "helps with code review", "improves output quality" — Claude has nothing to match against. The description is the only signal Claude has for trigger decisions. It's not metadata; it's the routing rule. Fix. Rewrite the description with the exact phrases users actually say in prompts. Not synonyms. Not category labels. The verbatim words. Bad: "This skill helps with TypeScript code quality." Better: "Auto-triggered when editing .ts/.tsx files. Use when the user says 'review this', 'lint this', 'check types', 'fix the errors', or after writing TypeScript code." Anthropic's authoring guide caps description + when_to_use at 1,536 characters — use them. (source)

Cause 2: Skill-budget overflow

Symptom. Skill triggers in a small project, doesn't trigger after you install five other skills, and /doctor shows budget usage near 100%. Diagnosis. Claude Code loads every installed skill's description into context at session start. The default budget is 1% of the model's context window. Once it overflows, newer or lower-priority skills get dropped silently. There is no warning. Fix. Three options:
  1. Raise the budget: export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 (default is around 10000 in our measurements).
  1. Trim other skills you don't actively use.
  1. Move rarely-used skills into a plugin and disable the plugin between sessions.
Run /doctor to see your current usage. (source: Obra)

Cause 3: Multi-line YAML description (Prettier ate it)

Symptom. Skill works fine until you run Prettier or commit through certain editors, then stops triggering entirely. Diagnosis. Prettier reformats long single-line YAML strings into multi-line folded scalars. Claude Code's skill parser handles this inconsistently — some versions silently drop multi-line description fields. Fix. Keep description on a single line, even if it's long. Add to your .prettierignore: `` /SKILL.md ` Or wrap the description in a >- block scalar explicitly — but the safer fix is single-line + Prettier ignore. Verified against issue #11266.

Cause 4: Wrong directory

Symptom. /skill-name returns "skill not found". Diagnosis. Claude Code looks in four locations, in priority order:
  1. Enterprise managed settings
  1. ~/.claude/skills//SKILL.md (personal, across projects)
  1. .claude/skills//SKILL.md (project)
  1. /skills//SKILL.md (plugin)
If your skill is at ~/.claude/skills/SKILL.md (no subfolder), or at ~/.claude/my-skill/SKILL.md (missing skills/), Claude won't see it. Fix. Confirm the path is /skills//SKILL.md. The skills folder is mandatory. The skill name folder is mandatory. (source: code.claude.com/docs/en/skills "Where skills live")

Cause 5: Double-nested folder after unzip

Symptom. You downloaded a skill release, extracted it, and now /skill-name doesn't work. The files are there. Diagnosis. GitHub release zips wrap everything in a top-level folder like superpowers-1.0.0/. After unzip you have ~/.claude/skills/superpowers-1.0.0/skills/writing-skills/SKILL.md — one level too deep. Fix. Move the contents up one level, or use tar --strip-components=1 on extract: `bash tar -xzf superpowers.tar.gz --strip-components=1 -C ~/.claude/skills/ ` This is the single most common cause for first-time skill users.

Cause 6: Claude Code didn't restart after first skill creation

Symptom. You created ~/.claude/skills/ for the first time (it didn't exist before), added a skill, and Claude can't find it. Restarting Claude Code fixes it immediately. Diagnosis. Claude Code probes the top-level skills directory at startup. If the directory didn't exist when Claude Code launched, it doesn't poll it later. Fix. Restart Claude Code after creating a top-level skills directory for the first time. After that, in-session reloads work for adding new skills, but the directory itself must exist at startup.

Cause 7: disable-model-invocation: true is set

Symptom. /skill-name works perfectly. Claude never auto-picks the skill. Diagnosis. The frontmatter contains disable-model-invocation: true. This is a deliberate gate — the skill is user-invocable only. Some community skills set this for safety; some inherit it from a template without realizing. Fix. Remove the line or set it to false: `yaml
name: my-skill description: ... disable-model-invocation: false # or remove the field entirely
` (source: code.claude.com/docs/en/skills frontmatter reference)

Cause 8: The task is simple enough that Claude solves it without invoking

Symptom. Your skill is well-described, well-located, budget is fine, and Claude still doesn't invoke it for simple prompts. Diagnosis. Claude makes a cost/benefit decision per skill: "is the routing overhead worth it for this task?" For trivial tasks ("rename this variable", "add a console.log"), the answer is no. The skill is fine; the prompt doesn't need it. Fix. Either don't worry about it (the system is working), or make your test prompts more representative of the work the skill is actually designed for. If the skill handles "review a 200-line component", don't test it with "what's 2+2".

Where this fails

These 8 causes cover the diagnoses we can name. There's a ninth class we can't fully explain: The "model just didn't feel like it" case.* Claude 4.6 and Claude Opus 4.7 occasionally don't invoke a skill that perfectly matches the description, for reasons not visible from the outside. We've seen this on 2 of 100 audited skills. Workaround: invoke explicitly with /skill-name. If you find a reproducible case, file an issue at github.com/anthropics/claude-code with the exact prompt and skill SKILL.md. We also did not* test whether the failure-rate differs between Sonnet 4.6 and Opus 4.7 — anecdotally Opus is more aggressive about invoking skills, but we don't have a measured number.

What to read next

Sources

Related GitHub projects

@anthropics

claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

⭐ 122,880

Frequently asked

How do I know if my skill is loaded at all?
Run `/doctor` inside a Claude Code session. It lists every skill currently loaded and reports skill-budget usage. If your skill isn't in the list, it isn't loaded — that's a directory-location issue (cause #4) or a YAML parse failure (cause #3). If it's in the list but never triggers, it's a description issue (cause #1) or a budget overflow (cause #2).
What is the 'skill budget'?
Claude Code loads every installed skill's description into context at session start. The total budget defaults to 1% of the model's context window (so roughly 10k tokens on Sonnet 4.6, 20k tokens at 1M context on Opus 4.7). When you exceed it, newer skills get dropped silently. Set `SLASH_COMMAND_TOOL_CHAR_BUDGET=30000` to raise it, or trim other skills. ([source: Obra debugging post](https://blog.fsck.com/2025/12/17/claude-code-skills-not-triggering/))
Why does my skill trigger sometimes but not always?
Usually trigger precision. Your description matches some phrasings of the user's prompt but not others. The fix is to widen the description with the exact phrases users actually say — not synonyms, the actual words. Anthropic's authoring docs call this 'pushy description' as an anti-pattern; the inverse — a too-narrow description — is more common and harder to diagnose.
Does Claude Code re-read my SKILL.md after I edit it?
Only at session start. If you edit `SKILL.md` mid-session, you must restart Claude Code (or run `/reload` on recent versions) to pick up the change. This catches everyone at least once.
Can I force a skill to trigger?
Yes. Type `/skill-name` directly, or in the prompt say 'use the X skill to do Y'. This bypasses model-invocation entirely. It also tells you whether the skill is loaded at all — if `/skill-name` fails, the skill isn't installed where Claude expects it.
What does `disable-model-invocation: true` do?
It tells Claude Code that this skill is user-invocable only — Claude won't pick it autonomously. Useful for destructive skills you want gated behind explicit `/command` invocation. If you set this by accident, your skill will never auto-trigger no matter how good the description. ([source: code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills))

Related topics