claude-md-improver

Q: How do I install claude-md-improver?

Run npx skills add https://github.com/anthropics/claude-plugins-official --skill claude-md-improver in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/claude-md-improver/ (personal) or .claude/skills/claude-md-improver/ (project).

by anthropics OfficialSecurity

Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".

Installs: 12.8K
Last 24h: +115
Trending rank: #1826
Security: Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/anthropics/claude-plugins-official --skill claude-md-improver

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads claude-md-improver automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill includes some security considerations such as indirect prompt injection risks and access to local configuration files. While these warrant review, they are part of the skill's intended functionality for auditing project documentation. See detailed analysis for context.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

Runlayer WarnMEDIUM ·1/4 files flagged

ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed

SKILL.md

The instructions your agent reads when the skill is triggered.

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 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 diff or quoted block)
- Brief explanation of why this helps future sessions

Diff Format:

### Update: ./CLAUDE.md

**Why:** Build command was missing, causing confusion about how to run the project.

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```


### Phase 5: Apply Updates

After user approval, apply changes using the Edit tool. Preserve existing content structure.

## Templates

See [references/templates.md](references/templates.md) for CLAUDE.md templates by project type.

## Common Issues to Flag

1. **Stale commands**: Build commands that no longer work
2. **Missing dependencies**: Required tools not mentioned
3. **Outdated architecture**: File structure that's changed
4. **Missing environment setup**: Required env vars or config
5. **Broken test commands**: Test scripts that have changed
6. **Undocumented gotchas**: Non-obvious patterns not captured

## User Tips to Share

When presenting recommendations, remind users:

- **`#` key shortcut**: During a Claude session, press `#` to have Claude auto-incorporate learnings into CLAUDE.md
- **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
- **Actionable commands**: All documented commands should be copy-paste ready
- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
- **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`

## What Makes a Great CLAUDE.md

**Key principles:**
- Concise and human-readable
- Actionable commands that can be copy-pasted
- Project-specific patterns, not generic advice
- Non-obvious gotchas and warnings

**Recommended sections** (use only what's relevant):
- Commands (build, test, dev, lint)
- Architecture (directory structure)
- Key Files (entry points, config)
- Code Style (project conventions)
- Environment (required vars, setup)
- Testing (commands, patterns)
- Gotchas (quirks, common mistakes)
- Workflow (when to do what)

FAQ

What does the claude-md-improver skill do?

How do I install claude-md-improver?

Run npx skills add https://github.com/anthropics/claude-plugins-official --skill claude-md-improver in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/claude-md-improver/ (personal) or .claude/skills/claude-md-improver/ (project).

Which AI agents can use claude-md-improver?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is claude-md-improver safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains claude-md-improver?

It is published by anthropics in anthropics/claude-plugins-official, and it is an official skill from the maker of the technology it covers. It has 12,822 recorded installs.