craft-memory
Crafting effective CLAUDE.md files. Project memory that Claude won't ignore.
SKILL.mdplugins/kernel/skills/craft-memory/SKILL.md
GitHubSkill: Craft Memory
"Would removing this line cause Claude to make mistakes? If not, cut it." — Anthropic
Source of Truth
Read these first. Every time. The spec evolves.
The Hierarchy
| Level | Location | Purpose |
|---|---|---|
| Organization | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md<br>Linux: /etc/claude-code/CLAUDE.md<br>Windows: C:\Program Files\ClaudeCode\CLAUDE.md |
Constraints |
| User | ~/.claude/CLAUDE.md |
Preferences |
| Project | ./CLAUDE.md or .claude/CLAUDE.md |
Context |
| Local | ./CLAUDE.local.md (auto-gitignored) |
Personal |
| Rules | .claude/rules/*.md |
Modular |
Higher levels load first and take precedence.
The Rules
1. Under 150 Lines
Bloated files get ignored. If Claude violates a rule you wrote, the file is too long.
2. Specific Over Vague
| Wrong | Right |
|---|---|
| Format code properly | Use 2-space indentation |
| Write good tests | Tests must cover error paths |
| Follow best practices | Validate input with Zod |
3. Include What Claude Can't Infer
| Include | Exclude |
|---|---|
| Commands Claude can't guess | Anything in package.json |
| Style rules that differ from defaults | Standard language conventions |
| Testing instructions | Detailed API docs (import instead) |
| Branch/PR conventions | Frequently changing info |
| Architectural decisions | File-by-file descriptions |
| Environment quirks | "Write clean code" |
| Common gotchas | Tutorials |
Deeper
| mechanism | imports, path scoping, and how nesting loads |
| protocol | discover, interview, generate, split |
| good | two files that work, whole |
| scoping | a monorepo, and what imports compose |
| bad | files that get ignored, and why |
Anti-Patterns
| Pattern | Why It Fails |
|---|---|
| Duplicate README | Wastes tokens, drifts |
| Giant monorepo file | No conditional loading |
Skip /memory |
Duplicate existing rules |