Claude Md Improver
Audit every CLAUDE.md in a repo, get a quality report, then apply approved fixes so Claude Code loads better project memory.
Overview
claude-md-improver is an agent skill most often used in Build (also Operate, Ship) that audits CLAUDE.md files across a repository and applies approved improvements so Claude Code gets optimal project context.
Install
npx skills add https://github.com/anthropics/claude-plugins-official --skill claude-md-improverWhat is this skill?
- Discovers CLAUDE.md, .claude.md, .claude.local.md, and nested monorepo paths via scripted find
- Scores files against templates and outputs a quality report before any edits
- Writes targeted CLAUDE.md updates only after user approval on the report
- Covers project root, gitignored local overrides, global defaults, and package-level context
- Explicit workflow: Phase 1 discovery → evaluation → approved maintenance pass
- 3-phase workflow: discovery, quality report, approved updates
- find command covers CLAUDE.md, .claude.md, and .claude.local.md
Adoption & trust: 5.8k installs on skills.sh; 29.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agents keep missing repo conventions because CLAUDE.md files are missing, duplicated, outdated, or scattered across monorepo packages.
Who is it for?
Teams and solo builders standardizing Claude Code context after refactors, monorepo splits, or repeated agent mistakes tied to weak instructions.
Skip if: Repos where you only need a one-off sentence added to CLAUDE.md without a scan, or when you forbid any agent writes to shared project memory files.
When should I use this skill?
User asks to check, audit, update, improve, or fix CLAUDE.md files, or mentions CLAUDE.md maintenance or project memory optimization.
What do I get? / Deliverables
You get a concrete quality report on every discovered CLAUDE.md and, after approval, targeted file updates that align project memory with templates and your workflow.
- CLAUDE.md quality report
- Targeted CLAUDE.md updates after approval
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build → agent-tooling because the artifact is CLAUDE.md project memory that shapes how coding agents behave in the codebase. Agent-tooling fits skills that tune Claude-specific context files (root, monorepo packages, local overrides), not application feature code.
Where it fits
After cloning a monorepo, scan package-level CLAUDE.md files and align them with a root template before heavy agent refactors.
Post-release, re-audit CLAUDE.md when agents start ignoring new deploy or testing conventions.
Before a security-sensitive merge, verify CLAUDE.md documents required review steps agents must follow.
Turn implicit README conventions into structured CLAUDE.md sections agents actually load every session.
How it compares
Use instead of manually grepping for CLAUDE.md and guessing what agents need—this skill packages discovery, scoring, and gated edits.
Common Questions / FAQ
Who is claude-md-improver for?
Solo and indie developers using Claude Code (or similar agents) who want auditable, team-safe maintenance of CLAUDE.md and related project memory files.
When should I use claude-md-improver?
Use during Build when setting up agent-tooling context, during Operate when memory drifts after releases, and during Ship review when you want agents to follow security and workflow rules documented in CLAUDE.md; also when you ask to check, audit, update, or fix CLAUDE.md or ment
Is claude-md-improver safe to install?
It can edit CLAUDE.md after you approve its report; review the Security Audits panel on this Prism page and restrict use on branches where you do not want agent-written context changes.
SKILL.md
READMESKILL.md - Claude Md Improver
# 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: ```bash 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):** 1. **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 2. **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 3. **Show diffs** - For each change, show: - Which CLAUDE.md file to update - The specific addition (as a d