Claude Code Skills Not Working? The 7 Failure Modes and How to Fix Each One

Summary:

1. Seven failure modes: not loading, conflicts, vague instructions, context overflow, loop runaway, hook mismatch, Claude updates.
2. Real debugging session: Jest appearing despite Vitest skill. Root cause found in 5 minutes.
3. Diagnostic commands for each failure mode.
4. Hard limits you cannot fix with better skills.
5. Seven-point troubleshooting checklist to run first.

Your skill file is in the directory. You restarted the session. Claude still ignores your rules. This is the debugging guide.

Seven failure modes cover every skills problem I’ve seen. Each one has a specific diagnosis and a specific fix.

Failure Mode 1: Skill not loading?

The most common problem. Three causes, three checks.

# Check 1: Correct path? (see https://docs.anthropic.com/en/docs/claude-code for directory structure)
ls -la .claude/skills/
# Must be .claude/skills/ (not skills/ at root, not .claude/commands/)

# Check 2: Correct extension?
file .claude/skills/*
# Watch for hidden extensions: .md.txt, .md.bak
# macOS TextEdit and some editors silently append .txt

# Check 3: Session restarted?
# Claude reads skills at session start ONLY.
# Adding or modifying a skill mid-session has NO effect.
# Exit Claude Code completely. Re-enter.

Real example: a developer spent an hour debugging a skill that wouldn’t load. Files looked correct in Finder. File names appeared as .md. Running file .claude/skills/* revealed every file was actually .md.txt because they used TextEdit with the hidden extension setting enabled.

Fix: rename the files or use a code editor that shows true extensions (VS Code, Sublime, vim).

# Bulk fix for hidden .txt extensions
for f in .claude/skills/*.md.txt; do
  mv "$f" "${f%.txt}"
done

Failure Mode 2: Skills conflicting?

Two skills give contradicting instructions. Claude follows one and ignores the other, and which one wins is unpredictable.

Diagnosis:

# Find specific conflicts
grep -r "semicolons" .claude/skills/
# If two files have opposing semicolon rules, that's your conflict

grep -r "jest\|Jest\|vitest\|Vitest" .claude/skills/
# Two files mentioning different test frameworks = guaranteed conflict

grep -r "default export\|named export" .claude/skills/
# Opposing export rules in different files

Real debugging session: A developer’s Vitest skill was being ignored. Claude kept generating Jest imports despite 02-testing/test-standards.md specifying Vitest. The tests ran. They passed. But the imports were wrong.

Root cause: the code review skill in 09-communication/code-review.md contained the line “check that tests follow Jest best practices.” That single mention of Jest in a higher-numbered folder overrode the testing skill. Fixed in 5 minutes by changing the line to “check that tests follow the project’s test framework conventions.”

# The fix was one line
# Before (in 09-communication/code-review.md):
#   "check that tests follow Jest best practices"
# After:
#   "check that tests follow the project's test framework conventions"

Failure Mode 3: Instructions too vague?

A skill says “write clean code” or “follow best practices.” Claude interprets this differently every session.

The test: ask yourself “Could I write an automated lint rule for this instruction?” If the answer is no, the instruction is too vague.

# Vague (fails the lint rule test)
- Write clean, readable code
- Follow best practices for error handling
- Use appropriate naming conventions

# Specific (passes the lint rule test)
- Function names: verb + noun, camelCase (e.g., fetchUserProfile)
- Error handling: every catch block must log error.message and rethrow
- Max function length: 30 lines. Split at logical boundaries if longer.

Every instruction in a skill file should be specific enough that you could write a linter to check for it. “Clean code” is not lintable. “Function names must be verb + noun in camelCase” is.

Failure Mode 4: Context overflow?

Too many skills, too many words. Claude’s attention spreads thin and rules start getting ignored.

# Check total skills word count
wc -w .claude/skills/**/*.md
# Keep always-active skills under 5,000 words total

# Check individual skill sizes
for f in .claude/skills/**/*.md; do
  words=$(wc -w < "$f")
  lines=$(wc -l < "$f")
  echo "$f: $words words, $lines lines"
done | sort -t: -k2 -n -r | head -10
# Top 10 largest skills, candidates for trimming

The hard limit: 5,000 words across all always-active skills. Beyond that, Claude gives partial attention to each file. If you’re at 7,000 words, you need to cut 2,000 or restructure some skills as on-demand rather than always-active.

Failure Mode 5: Self-improving skill runaway?

A self-improving skill without exit conditions grows uncontrollably. Rules multiply, contradict each other, and token costs spike.

# Check for runaway skills
for f in .claude/skills/**/*.md; do
  if grep -q "Self-Evaluation\|self-improving" "$f"; then
    lines=$(wc -l < "$f")
    echo "SELF-IMPROVING: $f ($lines lines)"
    if [ "$lines" -gt 60 ]; then
      echo "  WARNING: OVER 60 LINES, likely runaway"
    fi
  fi
done

# Emergency revert for a runaway skill
git checkout HEAD~1 -- .claude/skills/code-review.md
# Restores the previous version from git history

Every self-improving skill needs three exit conditions: evaluate at most once per session, update at most once per day, max file size 60 lines.

Failure Mode 6: Hook mismatch?

A hook fires on the wrong event or wrong file pattern.

Diagnosis: the hook runs but checks irrelevant files, or it doesn’t run when it should.

Check the event (is it git:pre-commit or file:save?), the pattern (is src/**/*.ts actually matching your source files?), and the blocking option (is a non-blocking hook failing silently?).

Failure Mode 7: Claude updates break skills?

Anthropic updates Claude’s behavior. A skill that worked last month stops working because Claude’s default behavior changed. Watch the Anthropic changelog and the Claude Code documentation for update announcements.

There’s no fix for this except testing. After any Claude update announcement, re-run your skill verification tests. Ask Claude the same prompts, check the same outputs.

What are the hard limits?

Five things you cannot fix with better skills:

1. You cannot make Claude smarter. Skills guide behavior, not capability. If Claude can’t solve a problem, a skill won’t help.
2. You cannot persist state between sessions. Each session starts fresh. Skills are read at startup but don’t carry runtime state.
3. You cannot execute code from skills. Skills are instructions, not scripts. They tell Claude what to do, not what to run.
4. Diminishing returns after 30 skills. Each additional skill adds less value and consumes more context. Trim non-performing skills before adding new ones.
5. Skills are only as good as your testing. An untested skill is a liability. If you haven’t verified the before/after, you don’t know if it works.

What’s the fastest way to diagnose any skills problem?

Run this 7-point checklist in order when any skill isn’t working:

# 1. Path check
ls .claude/skills/

# 2. Extension check
file .claude/skills/*

# 3. Session restarted?
# (Manual step: exit and re-enter Claude Code)

# 4. Conflict search
grep -rn "jest\|semicolons\|default export" .claude/skills/

# 5. Vague instruction check
# Read each skill: can you write a lint rule for every instruction?

# 6. Context size
wc -w .claude/skills/**/*.md | tail -1

# 7. Self-improving runaway check
wc -l .claude/skills/**/*.md | sort -n | tail -5

Most problems resolve at steps 1-3. If you get to step 7 and still have issues, the problem is likely a Claude update or a fundamental skill design issue.

What should you actually do?

• Right now, if skills aren’t working —> run checks 1-3 (path, extension, restart). This fixes the problem 80% of the time. Do not skip to advanced debugging before running the basics.
• If skills work inconsistently —> run the conflict grep from Failure Mode 2. Two files with opposing rules on the same topic is the most common cause of inconsistent output.
• Monthly —> run the full 7-point checklist as preventive maintenance. Catches context overflow, runaway self-improving skills, and dead files before they cause problems.

bottom_line

• Seven failure modes cover every skills debugging scenario. “Not loading” (path, extension, restart) accounts for 80% of all issues. The Claude Code docs have the canonical directory reference.
• Skill conflicts are the second most common problem. grep -r across your skills directory finds them in seconds. The Jest-vs-Vitest collision is the classic example.
• Hard limits exist: you cannot make Claude smarter, persist session state, or beat diminishing returns past 30 skills. Know the boundaries so you don’t waste time optimizing past them.