CC·FIELD MANUAL
No. CCA-2026-07
For Claude Code v2.x
LIVING DOC
$ man troubleshooting · GUIDE 03

Troubleshooting FAQ

Skill won't trigger, CLAUDE.md rules ignored, sessions getting dumber over time — how to diagnose and fix the five most common problems.

Skill won't trigger?
Nine times out of ten the description is too abstract. Add the three essentials: what it does (list concrete capabilities), when to use it, and the words users might actually say (cover casual phrasing). Then verify by making a matching request.
CLAUDE.md rules being ignored?
Run /memory first: the rule may live in a subdirectory file that has not lazy-loaded yet. Then check for two rules contradicting each other (Claude may pick either). For hard constraints that still wobble, rewrite them as a PreToolUse hook.
Sessions get dumber as they get longer?
Performance drops as context fills up. Cut unrelated tasks apart with /clear; on long tasks run /compact focus on the essentials at ~70% full; persist conclusions to CLAUDE.md or let auto memory (MEMORY.md) take over — never rely on chat history.
Is there a cost to installing many skills?
Resident cost is tiny (~100 tokens of metadata each), but overlapping descriptions blur matching. Keep only the best one per niche, and let each skill do exactly one thing.
Skill vs CLAUDE.md vs Hook vs MCP — who does what?
Hard facts and rules → CLAUDE.md; multi-step "how-to" → Skill (loaded on demand); actions that must be enforced → Hook; connecting external data and systems → MCP, then use a Skill to teach Claude how to use those tools well.

The division of labor, in one picture

Division of labor: CLAUDE.md holds facts, Skills hold how-to, Hooks enforce, MCP connects claude CLAUDE.md hard facts and rules injected every session Skill multi-step "how-to" loaded on task match Hook must-enforce actions lifecycle points, no moods MCP external data & systems wire in, then teach via a skill

← Back to guides