Why Your Claude Code Skills Aren't Working (7 Fixes)

Summary:

1. Seven specific failure modes that break Claude Code skills, with fixes for each.
2. Copy-paste diagnostic commands to identify the problem in under a minute.
3. A real 5-minute debugging session walkthrough from symptom to fix.
4. The 7-point troubleshooting checklist to tape to your monitor.

A developer’s editor saved skill files as .md.txt instead of .md. The real extension was hidden by the OS. Claude saw six .txt files and ignored them all. That’s the kind of problem this article solves. Stupid, invisible, five-minute problems that make you question your sanity.

Skills break in predictable ways. Once you know the patterns, debugging takes seconds instead of hours.

Quick triage — jump to the right section:

• Output looks identical with and without the skill → Failure 1 (not loading) or Failure 3 (too vague)
• Output is inconsistent (sometimes follows the rule, sometimes doesn’t) → Failure 2 (conflict)
• Output got worse after adding more skills → Failure 4 (context overflow) or Failure 5 (runaway loop)
• Hook-related: skill works manually but not from a hook → Failure 6 (hook-skill mismatch)
• Was working yesterday, nothing changed → Failure 7 (Claude update)

Failure 1: Skills not loading at all

The most common failure. You create a skill, restart Claude, and nothing changes.

# Run these five checks in order

# 1. File in the right place?
ls -la .claude/skills/

# 2. Real extension is .md? (catches hidden .txt suffix)
file .claude/skills/*.md

# 3. Can you read it? If yes, Claude can too.
cat .claude/skills/your-skill.md

# 4. Permissions OK?
chmod 644 .claude/skills/*.md

# 5. Ask Claude directly:
# "What skills are currently loaded for this project?"

If Claude lists your skill but output doesn’t change, the skill loaded but the instructions are too vague. See Failure 3.

Failure 2: Skill conflicts producing inconsistent output

Symptom: Claude sometimes uses semicolons and sometimes doesn’t. Sometimes writes tests one way, sometimes another. The inconsistency is the clue.

# Find which files mention the conflicting topic
grep -r "semicolons" .claude/skills/

# Broader conflict audit: check 15+ common overlap keywords
for keyword in semicolon import export test error log indent quote type return async naming format comment mock; do
  count=$(grep -rl "$keyword" .claude/skills/ 2>/dev/null | wc -l)
  if [ "$count" -gt 1 ]; then
    echo "'$keyword' in $count files:"
    grep -rl "$keyword" .claude/skills/
    echo ""
  fi
done

Fix: Decide which rule wins. Move it to a higher-numbered folder (Chapter 5 priority system). Remove the conflicting rule from the lower-priority skill. Or add an explicit exception: “Use semicolons everywhere except in test files.”

Failure 3: Skills too vague to change output

The skill loaded. Claude references it. But output looks the same.

Bad rule (does nothing)	Good rule (changes output)
Write clean code	Functions under 30 lines, extract helpers if longer
Follow best practices	Named exports only, never export default
Use good formatting	2-space indentation, no tabs, no semicolons
Handle errors properly	Custom error classes extending AppError, log at boundary only

The test: For every rule in your skill, ask: “Could I write an automated lint rule that checks this?” If yes, the rule is specific enough. If no, rewrite it.

Failure 4: Context window overflow from too many skills

Symptom: Claude gives shorter answers. Forgets things you said earlier. Starts ignoring some skills while following others.

# Check total skills size
find .claude/skills -name "*.md" -exec cat {} + | wc -w
# If over 5,000 words, you're impacting context

Fix: Convert “always active” skills to triggered skills. Keep always-active skills under 5,000 total words.

Keep always active	Convert to triggered
Code style, Stop slop	Deployment (when working on Dockerfiles or CI configs)
Testing standards	Migration review (when reviewing migration files)
Git commits	Security audit (when modifying auth or payment code)
Code review	Performance (when optimizing queries or caching)

The first column fires on every task. The second column fires only when the trigger matches. A 30-skill library where 6 are always-active and 24 are triggered loads roughly 300-500 tokens per task instead of 4,000+.

Failure 5: Self-improving loop gone wrong

Symptom: API bill spikes. Skill file has grown to 200+ lines. Instructions contradict each other. Output quality dropped.

Immediate fix:

# Find the last good version
git log --oneline .claude/skills/your-skill.md

# Restore it
git checkout [commit-hash] -- .claude/skills/your-skill.md

Root cause: Missing or weak exit conditions. Every self-improving skill needs three rules: evaluate at most once per session, update at most once per day, skip if no improvement needed. Plus a 60-line hard cap.

Failure 6: Hook-skill mismatch

Symptom: Hook fires but the wrong skill activates, or no skill activates. Error: “Hook fired, but no skill matched the trigger condition.”

Three checks:

1. Skill path in hook JSON. The action.skill field is relative to .claude/skills/. After reorganizing into folders, the path needs the folder: 09-communication/code-review not just code-review.
2. Trigger alignment. The hook’s prompt must describe a task that matches the skill’s trigger. Hook says “review this migration” but skill triggers “when writing code”? Mismatch.
3. Glob pattern. src/**/*.ts matches subdirectories. src/*.ts only matches files directly in src/. Missing ** is the most common cause.

Failure 7: Claude update breaks skills

Symptom: Skills that worked yesterday stopped today. Nothing changed on your end.

Check Anthropic’s changelog. Search for “skills,” “trigger,” or “context” in the release notes. Common breaking changes:

• Trigger condition syntax changes (keywords renamed or restructured)
• Context window size adjustments (your skills that fit before now overflow)
• Skill loading order changes (priority numbering behaves differently)
• Markdown parsing updates (headers or bullet formatting interpreted differently)

What to do: Re-test your three most important skills after every Claude Code update. If they still work, the rest probably do too. If one broke, check the changelog diff for the specific change.

Prevention: Pin your Claude Code version in team environments. Test new versions in a side project first.

Nate Herk documented this pattern across his community in “I Watched 100+ People Hit the Same Claude Skills Problems in Week One” (90 likes, 23 comments). The five most common week-one issues he tracked: skills that won’t trigger, context window overflows, zip file problems, security questions about skills running code, and not knowing how to evaluate whether a skill works. He built 10 debugging tools in response, including a skill-debugging-assistant and a token-budget-advisor.

For Anthropic’s official diagnostic guide, see the troubleshooting docs.

A real debugging session: 5 minutes

Symptom: Claude writes tests with Jest assertions even though the testing skill specifies Vitest.

Minute 1: Verify skill loaded. Asked Claude: “What testing framework should you use?” Response: “Vitest.” Skill loaded. It knew the answer. Just not applying it consistently.

Minute 2: Check conflicts. Ran grep -r "jest\|vitest" .claude/skills/. Testing skill mentioned Vitest (correct). Old code-review skill mentioned “check for Jest best practices” (wrong). Two files, contradictory instructions.

Minute 3: Check priority. Testing skill in 02-testing/. Code-review skill in 09-communication/. Higher number wins. Claude was prioritizing code-review’s Jest reference over testing’s Vitest requirement.

Minute 4: Fix. Edited code-review skill: replaced “Jest best practices” with “testing framework compliance (see testing skill).” Removed the framework-specific reference.

Minute 5: Verify. Restarted Claude. Asked for a test file. Vitest imports. Correct assertions. Done.

Without the systematic approach, this would have been 30 minutes of random edits and restarts.

What should you actually do?

• If Claude is ignoring your skill entirely: run the 5-check diagnostic from Failure 1. The fix is almost always file path, extension, or a stale session.
• If output is inconsistent: it’s a conflict. Run the grep audit from Failure 2. Two files mentioning the same topic with different rules is your answer.
• If everything was working and suddenly stopped: check if Claude Code updated. Pin your version in team environments.

The troubleshooting checklist

Print this. Tape it next to your monitor.

1. File in .claude/skills/ with .md extension?
2. Restarted Claude Code after creating the file?
3. grep -r "[your rule]" .claude/skills/ shows rule in exactly one file?
4. Skill’s trigger condition matches the task you’re testing?
5. Total word count of always-active skills under 5,000?
6. All hook paths updated after reorganizing skills?
7. Claude Code updated recently? Check changelog.

All seven pass and skill still broken? Create a minimal reproduction: one skill file, one test prompt, one expected behavior. Post it in the community with your Claude version number.

bottom_line

• Skills break in predictable ways. Seven failure modes cover 95% of problems. The diagnostic for each takes under a minute.
• Conflicts are the sneakiest failure. Run grep -r across your skills folder monthly. Any keyword in two files is a potential conflict.
• The 7-point checklist works every time. Most problems are invisible five-minute fixes, not complex architectural failures.