Guide · Agent skill
How to use the CLAUDE.md Improver agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The claude-md-improver skill gives an agent a repeatable process for checking the CLAUDE.md files in a repository. CLAUDE.md is a plain-text file that gives Claude Code standing context about a project, such as build commands, architecture and gotchas. This guide is for developers who use Claude Code on a project and want to know what the skill does, how to install it, and how to use it safely.
CLAUDE.md Improveranthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Download the skill ZIP. Get the claude-md-improver ZIP from the directory page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for all projects, or into the repository's .claude/skills/ for one project.
- 3Open your repository in Claude Code. Start a session in the project whose CLAUDE.md files you want to check.
- 4Ask for an audit. Request a CLAUDE.md audit or quality report in plain language.
- 5Review the quality report. Read the grades and issues for each CLAUDE.md file before deciding on changes.
- 6Approve or reject diffs. Accept only the proposed additions you have checked, then let the agent apply them.
What the skill makes the agent do
The skill runs in five phases. First it searches the repository for every CLAUDE.md file, including .claude.local.md and package-level files in monorepos. Then it scores each file against a quality rubric that covers commands and workflows, architecture clarity, non-obvious patterns, conciseness, currency and actionability.
After scoring, the agent writes a quality report with an overall grade and a file-by-file breakdown. Only after that does it propose targeted additions as diffs, and it edits files only after you approve.
- Discovery: finds CLAUDE.md, .claude.md and .claude.local.md files.
- Assessment: grades each file from A (90-100) to F (0-29).
- Report: lists issues and recommended additions before any change.
- Updates: shows diffs, waits for approval, then applies them with the Edit tool.
Install the claude-md-improver skill
Download the ZIP for this skill from the directory page. A skill is a folder containing a SKILL.md file and supporting files. This skill's folder includes SKILL.md, references/quality-criteria.md, references/templates.md and references/update-guidelines.md.
For personal use across all your projects, unzip the folder into ~/.claude/skills/. To limit it to one repository, unzip it into that project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need to type a special command. The skill's description tells the agent when to use it, so ask in plain language. Requests that match its description include asking to check, audit, update, improve or fix CLAUDE.md files, or mentioning CLAUDE.md maintenance or project memory optimization.
Start with an audit before asking for edits. A report-first request keeps you in control of what changes.
- "Audit the CLAUDE.md files in this repo and give me a quality report."
- "Check whether our CLAUDE.md is still accurate after the build changes."
- "Improve the CLAUDE.md files for each package in this monorepo."
- "Do some CLAUDE.md maintenance and show me the diffs before changing anything."
Read the quality report and approve changes
The report scores each file across six criteria. Commands/workflows, architecture clarity and actionability are weighted as high, and currency is also high. Non-obvious patterns and conciseness are medium. The report also lists the common issues the skill looks for, such as stale commands, missing dependencies, outdated architecture, missing environment setup, broken test commands and undocumented gotchas.
Review each proposed diff. The source says the skill is written to ask for confirmation first, but that approval step is part of its instructions and is not enforced by code, so check the diffs yourself before you say yes.
- Check that each proposed command still works.
- Remove additions that restate obvious code.
- Keep personal preferences in .claude.local.md rather than the shared file.
Keep CLAUDE.md useful over time
The skill's guidelines favour short files. Its update rules say to add only information that will help future sessions, and to avoid restating obvious details, generic best practices, or one-off fixes. Recommended sections include Commands, Architecture, Key Files, Code Style, Environment, Testing, Gotchas and Workflow, but you should use only the ones that apply.
During a Claude session you can press # to have Claude incorporate learnings into CLAUDE.md. Global defaults belong in ~/.claude/CLAUDE.md.
- Keep commands copy-paste ready.
- Prefer one line per concept over long explanations.
- Put user-wide preferences in ~/.claude/CLAUDE.md.
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50Safety notes before you run it
The skill runs scripts and declares Bash, Read, Glob, Grep and Edit access. It does not use the network. Because it reads CLAUDE.md files, it may quote their contents into the report. If a file contains secrets, do not run the skill on that repository until you have removed them, and check the report before sharing it.
Edits are applied only after you approve them, but that protection depends on the agent following its instructions. Review the proposed changes in version control so you can revert anything unexpected.
- Runs scripts: yes. Uses network: no.
- Repositories with secrets in CLAUDE.md files are a poor fit.
- Use git to review and roll back edits.
What people use it for
- Checking a single project's CLAUDE.md for stale build or test commands after tooling changes.
- Auditing a monorepo's package-level CLAUDE.md files so each package has accurate context.
- Getting a quality report on project memory before a team decides what to rewrite.
- Adding a newly discovered gotcha or testing approach to the shared CLAUDE.md after review.
Frequently asked questions
Is the claude-md-improver skill free?
The source material for this listing does not state pricing terms. It is published under the Apache-2.0 licence, which you should read in the repository to understand your rights. Check the directory page for any other cost details.
What do I need to run the claude-md-improver skill?
You need Claude Code or another agent that reads SKILL.md files, plus Bash, Read, Glob, Grep and Edit tool access. The skill runs scripts and does not use the network. It only affects projects that use CLAUDE.md.
How do I install the claude-md-improver skill?
Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one repository. In the Claude apps, upload it under Settings → Capabilities → Skills.
Will the skill change my CLAUDE.md files without asking?
The skill is written to produce a quality report, show diffs and wait for your approval before editing. That approval step is part of its instructions and is not enforced by code, so review every change before accepting it.
Can it audit CLAUDE.md files in a monorepo?
Yes. Its discovery phase searches the whole repository and includes package-level files such as ./packages/*/CLAUDE.md, and it reports on each file separately.
Why does my CLAUDE.md audit mention secrets?
The skill reads CLAUDE.md files and may quote their contents into the report. Remove any secrets from those files before running the audit, and do not share the report without checking it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain a repository used with Claude Code, especially a monorepo with several CLAUDE.md files, and want a graded report before any edits. Skip it if your project does not use CLAUDE.md or Claude Code, or if your CLAUDE.md files contain secrets you cannot remove first.
Download the skill