Claude Code Skill Not Triggering? 9 Fixes That Work

When a Claude Code skill is not triggering, the cause is almost always one of three things: the file is not where Claude Code looks (wrong path or a name that does not match the folder), the frontmatter does not parse (usually an unquoted colon), or the description does not match how you phrase the request. Start by running /skills. If the skill is missing from the list, it is a file or YAML problem. If it is listed but never fires on its own, it is a description or settings problem.

Work through the fixes below in order. Each one includes a quick check.

Step 0: Is the skill loaded at all?

Run this in Claude Code:

/skills

Then try to invoke it by name:

/your-skill-name

/skills shows it	/name works	Likely cause	Go to
No	No	Path, folder name, or YAML	Fixes 1 to 3
Yes	Yes, but never automatic	Description or invocation settings	Fixes 4 to 6
Yes	A different skill loads	Name collision or overlapping descriptions	Fixes 7 to 8
Yes	Loads, then gets ignored	Context budget or body problems	Fix 9

Fix 1: The SKILL.md is in the wrong place

Claude Code looks for exactly <skills-dir>/<skill-name>/SKILL.md. Check:

ls ~/.claude/skills/*/SKILL.md      # personal
ls .claude/skills/*/SKILL.md        # project, from the repo root

Common mistakes:

• Double nesting after unzipping: ~/.claude/skills/code-review/code-review/SKILL.md. Move the inner folder up one level.
• Loose file: ~/.claude/skills/SKILL.md, with no skill folder around it.
• Wrong case: skill.md or Skill.md. The file must be named SKILL.md.
• Wrong root: the project skill is in docs/.claude/skills/ but you started Claude Code at the repo root. Nested .claude/skills directories load only when you work in that subdirectory.
• Plugin layout: plugin skills live at <plugin>/skills/<name>/SKILL.md and are invoked as /<plugin>:<name>, not /<name>.

If you created ~/.claude/skills or .claude/skills for the first time during a running session, Claude Code may not be watching it yet. Run /reload-skills. Edits to skills inside directories that already existed are picked up live.

Fix 2: The name does not match the folder

The open standard requires name to match the parent directory. It must also be 1 to 64 characters of lowercase letters, digits, and hyphens, with no leading, trailing, or consecutive hyphens.

.claude/skills/code-review/SKILL.md   with   name: code-review     # good
.claude/skills/code-review/SKILL.md   with   name: codeReview      # bad: case
.claude/skills/CodeReview/SKILL.md    with   name: code-review     # bad: folder
.claude/skills/code_review/SKILL.md   with   name: code_review     # bad: underscore

A quick check for every skill at once:

for f in ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md; do
  [ -f "$f" ] || continue
  dir=$(basename "$(dirname "$f")")
  name=$(sed -n 's/^name:[[:space:]]*//p' "$f" | head -1 | tr -d '"'"'")
  [ "$dir" = "$name" ] || echo "MISMATCH: $f (folder=$dir, name=$name)"
done

Fix 3: The YAML frontmatter does not parse

A frontmatter error can make the whole skill invisible. The usual suspects:

Unquoted colons. This breaks because the colon after Note looks like the start of a nested mapping:

description: Reviews SQL migrations. Note: use when a PR touches migrations/

Quote the string:

description: "Reviews SQL migrations. Note: use when a PR touches migrations/"

Other frequent errors:

• Tabs instead of spaces for indentation
• Missing closing ---, or content before the opening ---
• A description starting with a character YAML treats specially, such as *, &, !, [, {, >, |, @, or a backtick
• Smart quotes pasted from a document instead of straight quotes

Parse it to be sure:

python3 -c "import sys,yaml; print(yaml.safe_load(open(sys.argv[1]).read().split('---')[1]))" .claude/skills/code-review/SKILL.md

Also check spelling. Claude Code ignores unknown keys, so disable-model-invokation: true does nothing and raises no error.

Fix 4: The description is too vague

If /name works but Claude never picks the skill up on its own, the description is not matching your requests. Claude decides from the description alone, before it has read the body.

# Too vague: what kind of testing? when?
description: Testing helper.

# Specific: capability, scope, and trigger phrases
description: Drives red-green-refactor test-driven development, writing one failing test at a time before any implementation. Use when the user asks for TDD, test-first development, or to add a feature "with tests first", or when fixing a bug that needs a regression test.

Rules that make descriptions trigger:

• State what it does and when to use it.
• Use the words people actually type: “flaky test,” “slow query,” “PR description.”
• Front-load the most important terms. Claude Code truncates description plus when_to_use at 1,536 characters in the skill listing.
• Write in the third person (“Reviews…”, not “I can help you…”).

Test in a fresh session each time, with three or four phrasings that should trigger and two that should not. The skill-description-tuning skill runs this loop for you.

Fix 5: Automatic invocation is turned off

Check the frontmatter for:

disable-model-invocation: true

This makes the skill manual-only by design: only /name loads it. It is the right setting for deploy or publish skills, but a common copy-paste leftover elsewhere. Remove it, or set it to false, if you want Claude to trigger the skill.

The opposite setting, user-invocable: false, hides a skill from the / menu while still letting Claude invoke it. If you cannot find your skill when typing /, check for this.

Fix 6: The paths filter excludes your files

paths:
  - "src/db/**/*.sql"

A paths glob limits when a skill applies. If your migrations are in migrations/ rather than src/db/, the skill will stay quiet. Widen or remove the glob and test again.

Fix 7: Another skill with the same name wins

When two skills share a name, Claude Code applies precedence:

1. Enterprise (managed) skills
2. Personal skills in ~/.claude/skills
3. Project skills in .claude/skills

So if you have an old personal code-review skill, the project’s code-review never loads for you, even though it works for teammates. Check both locations:

ls -d ~/.claude/skills/code-review .claude/skills/code-review 2>/dev/null

Rename one of them, or delete the stale copy. Also note that a skill overrides a same-named file in .claude/commands/, which can make an old command seem to “stop working.” Plugin skills are namespaced, so they never collide with these.

Fix 8: Descriptions overlap and Claude picks the other skill

If you have code-review, pr-review, and security-review, a request like “review this PR” matches all three. Claude picks one, and it may not be the one you meant.

Make descriptions mutually exclusive:

# code-review
description: Reviews code changes for correctness, readability, and test coverage. Use for general PR or diff reviews. For security-focused reviews use owasp-review instead.

Saying what a skill is not for is as useful as saying what it is for. If two skills keep colliding, consider merging them.

Fix 9: The skill loads but Claude ignores parts of it

If the skill loads but steps get skipped, look at the body and the context budget:

• The body is too long. Keep SKILL.md under about 500 lines. Long bodies dilute the important instructions. Move detail into references/ files linked from SKILL.md.
• References are nested. SKILL.md links to a.md, which links to b.md. Claude may read b.md only partially or not at all. Keep references one level deep.
• Too many skills installed. Every skill’s description sits in context. Dozens of overlapping descriptions make each one less distinctive. Run /context to see the cost and remove skills you do not use.
• Long sessions. After auto-compaction, Claude Code re-attaches the latest invocation of each skill, but only the first 5,000 tokens per skill, within a 25,000-token shared budget. Instructions near the end of a very long skill can be lost. Put critical rules near the top, or invoke the skill again.
• No checklist. For multi-step procedures, ask Claude to copy a checklist into its response and tick items off. It noticeably reduces skipped steps.

Dynamic context commands fail

If the skill contains !`command` lines, a failing command aborts loading the skill. Typical causes are a missing CLI (gh not installed), running outside a git repo, or a permission rule blocking the command.

- Open PRs: !`gh pr list --limit 5 || true`

Adding || true lets the skill load even when the command fails. Also check that "disableSkillShellExecution": true is not set in your settings or your organization’s managed settings; with it on, these commands do not run.

Still stuck?

Strip the skill down to a minimal version, just name, a one-line description, and one sentence of body, and confirm that loads. Then add pieces back one at a time until it breaks. That isolates the problem in a few minutes.

Next steps

• Field-by-field rules: SKILL.md format reference
• Where skills load from and in what order: Personal vs project skills
• Write descriptions that trigger: Skill authoring best practices
• Tools: skill-description-tuning, skill-authoring
• Official docs: code.claude.com/docs/en/skills