CLAUDE.md Improver
Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure Claude Code has optimal project context.
**This skill can write to CLAUDE.md files.** After presenting a quality report and getting user approval, it updates CLAUDE.md files with targeted improvements.
Workflow
Phase 1: Discovery
Find all CLAUDE.md files in the repository:
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50**File Types & Locations:**
| Type | Location | Purpose | |------|----------|---------| | Project root | `./CLAUDE.md` | Primary project context (checked into git, shared with team) | | Local overrides | `./.claude.local.md` | Personal/local settings (gitignored, not shared) | | Global defaults | `~/.claude/CLAUDE.md` | User-wide defaults across all projects | | Package-specific | `./packages/*/CLAUDE.md` | Module-level context in monorepos | | Subdirectory | Any nested location | Feature/domain-specific context |
**Note:** Claude auto-discovers CLAUDE.md files in parent directories, making monorepo setups work automatically.
Phase 2: Quality Assessment
For each CLAUDE.md file, evaluate against quality criteria. See [references/quality-criteria.md](references/quality-criteria.md) for detailed rubrics.
**Quick Assessment Checklist:**
| Criterion | Weight | Check | |-----------|--------|-------| | Commands/workflows documented | High | Are build/test/deploy commands present? | | Architecture clarity | High | Can Claude understand the codebase structure? | | Non-obvious patterns | Medium | Are gotchas and quirks documented? | | Conciseness | Medium | No verbose explanations or obvious info? | | Currency | High | Does it reflect current codebase state? | | Actionability | High | Are instructions executable, not vague? |
**Quality Scores:**
- **A (90-100)**: Comprehensive, current, actionable
- **B (70-89)**: Good coverage, minor gaps
- **C (50-69)**: Basic info, missing key sections
- **D (30-49)**: Sparse or outdated
- **F (0-29)**: Missing or severely outdated
Phase 3: Quality Report Output
**ALWAYS output the quality report BEFORE making any updates.**
Format:
## CLAUDE.md Quality Report
### Summary
- Files found: X
- Average score: X/100
- Files needing update: X
### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**
| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |
**Issues:**
- [List specific problems]
**Recommended additions:**
- [List what should be added]
#### 2. ./packages/api/CLAUDE.md (Package-specific)
...Phase 4: Targeted Updates
After outputting the quality report, ask user for confirmation before updating.
**Update Guidelines (Critical):**
- **Propose targeted additions only** - Focus on genuinely useful info:
- Commands or workflows discovered during analysis
- Gotchas or non-obvious patterns found in code
- Package relationships that weren't clear
- Testing approaches that work
- Configuration quirks
- **Keep it minimal** - Avoid:
- Restating what's obvious from the code
- Generic best practices already covered
- One-off fixes unlikely to recur
- Verbose explanations when a one-liner suffices
- **Show diffs** - For each change, show:
- Which CLAUDE.md file to update
- The specific addition (as a d
<!-- truncated -->
