Claude Code Skills Not Working? 7 Fixes

Summary:

1. Seven failure modes that break Claude Code skills, with the fix command for each.
2. The directory + SKILL.md spec the troubleshooter is built on (most guides get this wrong).
3. The two myths to delete: “restart to load” and numeric-folder-priority.
4. A 7-point checklist to tape to your monitor.

Claude Code skills not working is almost never a complex failure. It’s a flat file that should be a directory, or a missing description: field. About 70% of “my skills are broken” cases resolve at the first check. Older troubleshooting guides send you in circles because they’re built on the wrong spec (flat .md files, “restart Claude Code,” folder-number priority). This one is built on the real one.

What does a working skill actually look like?

A working skill is a directory under .claude/skills/ containing a file named exactly SKILL.md, and that file has a description: in its YAML frontmatter. From the official Claude Code skills docs:

my-skill/
├── SKILL.md           # Main instructions (required)
├── examples/
│   └── sample.md      # Example output
└── scripts/
    └── validate.sh    # Script Claude can execute

The docs are explicit: “The SKILL.md contains the main instructions and is required.” The description: field is what Claude matches against to decide when to invoke the skill. A flat .claude/skills/code-style.md is the old slash-command pattern, not a skill. That single misunderstanding causes most failures.

The 7 failure modes (in priority order)

Fix 1: It must be a directory with SKILL.md

ls -la .claude/skills/
ls .claude/skills/code-style/   # should print: SKILL.md

Each entry must be a directory. If ls shows code-style.md instead of code-style/, that’s the problem. Most failures stop here.

Fix 2: The description field is mandatory

head -5 .claude/skills/code-style/SKILL.md

No description: means the skill loads into metadata but Claude has nothing to match against, so it never auto-invokes. The skill is present and dormant. Add a specific one-sentence description: and it fires.

Fix 3: The rule must live in exactly one skill

grep -r "semicolon" .claude/skills/

Swap semicolon for whatever rule Claude follows inconsistently. If two SKILL.md files mention the same topic with different instructions, you found the conflict.

Fix 4: Conflicting descriptions must not overlap

If two skills’ description: fields could both match the same task (“Use this when writing code” + “Use this when writing TypeScript”), Claude loads both and averages contradictory advice. The fix is tightening each description: to a non-overlapping scope, not renaming folders. If the rules genuinely contradict in the same scope, pick one and delete the other.

Fix 5: Narrow the paths glob

A skill with paths: ["**/*.ts"] auto-invokes on every TypeScript file. Scope it: paths: ["src/api/**/*.ts"]. Broad globs are why a skill fires when it shouldn’t and crowds the context.

Fix 6: Hooks need real event names

If a skill is invoked via a hook that won’t fire, the event name is usually fictional. Real: PreToolUse, PostToolUse, FileChanged, SessionStart, Stop. Not real: file:save, git:pre-commit, command:fail. Hook config lives in settings.json, not .claude/hooks/*.json.

Fix 7: Check the Claude Code version

Skills that worked yesterday and broke today with no change on your end usually mean the spec moved in an update. Check the changelog at https://code.claude.com/docs/en/ and match your files to the current spec.

Two myths that waste hours

These are in every old troubleshooting guide and both are wrong:

• “Restart Claude Code to load a new skill.” Live change detection picks up new skills inside the current session. The only exception: if .claude/skills/ itself didn’t exist when the session started and you just created it, you need a fresh session for Claude to start watching the directory. Individual skill files inside an existing directory are picked up live.
• “Numbered folders set priority; move the winning rule to a higher number.” Claude does not read priority off folder names. There is no intra-project folder-number priority. The only override order is enterprise > personal > project (the more global location wins, which is counter-intuitive). Numeric prefixes only keep your directory tidy when you ls it.

A reference reality check, because the honesty matters: skills don’t make Claude smarter, don’t persist session state, and don’t execute code. They change behavior and add context. A skill that’s never tested against real output might be doing nothing. The fix path above assumes the skill is worth loading; vague skills “load” and still change nothing.

A real 5-minute debugging session

Symptom: Claude wrote Jest assertions even though the testing skill specified Vitest.

1. Asked Claude “what test framework should you use here?” It answered “Vitest.” So the skill loaded.
2. grep -r "jest\|vitest" .claude/skills/ showed the testing skill said Vitest (correct) and an old code-review skill said “check Jest best practices” (wrong).
3. Read both description: fields. The code-review skill’s was “Use this when reviewing code” with no scope, so it co-loaded on a test-file review.
4. Dropped the Jest line from the code-review skill and tightened its description: to “reviewing PRs against bug/security/performance criteria.”
5. Re-ran. Vitest. Fixed. Five minutes, because the order was: verify loaded, check description: scope, find the overlap.

What should you actually do?

• If Claude ignores a skill: run Fix 1 then Fix 2. Don’t rewrite the body first; structure and description: cause most failures.
• If output is inconsistent: it’s a conflict (Fix 3 and 4). Two overlapping description: fields, not a folder-number problem.
• If it broke after an update: Fix 7. Match files to the current docs spec.

The 7-point checklist, taped to the monitor: directory+SKILL.md → description: present → rule in one file → descriptions non-overlapping → paths: narrow → real hook events → Claude Code current.

bottom_line

• “Skills not working” is a flat-file or missing-description: problem ~70% of the time. Check those two before anything else.
• “Restart to load” and numeric-folder-priority are myths. Believing them is how a five-minute fix becomes a thirty-minute one.
• A skill you never test against real output might be loading perfectly and doing nothing. Loading is not the same as working.