Let's grow CLAUDE.md with Anthropic's official claude-md-management plugin
Table of Contents
When did you last review your CLAUDE.md? Build commands changed, test procedures changed, directory structure reorganized. Have you been keeping up with each of those changes? Honestly, I tend to slack off. And by the time I notice, the classic problem has already occurred: Claude Code is relying on outdated information and doing something completely off the mark.
The Anthropic official claude-md-management plugin addresses this problem head-on. Developed and maintained by Anthropic itself—the same team behind Claude Code—this plugin comes bundled with a skill that scores the quality of your CLAUDE.md and a command that incorporates lessons learned during a session into your CLAUDE.md. Put simply, it's a "CLAUDE.md housekeeping" plugin.
In this article, I'll cover everything: what's inside this plugin, how to install it, how to actually use it, and best practices for how to grow your CLAUDE.md over time.
Why the freshness of CLAUDE.md matters
CLAUDE.md is the "project manual" that Claude Code reads at the start of every session. By writing down build commands, architecture, common pitfalls, and other information that's hard to glean from the code alone, you enable Claude to start working with an understanding of the project's "atmosphere" right from the beginning.
However, this comes with a side effect. Because the contents of CLAUDE.md are sent as part of the prompt every time, outdated or redundant information will mislead Claude and waste tokens. It's a common story: the codebase itself gets continuously refined through refactoring, while CLAUDE.md is left frozen in the state it was in months ago.
claude-md-management is a plugin designed to solve this "write-and-forget problem" through systematic means.
Two tools: auditing and capturing
This plugin contains two tools with distinct roles. Since they're easy to mix up, let's clarify them first.
claude-md-improver (skill) | /revise-claude-md (command) | |
|---|---|---|
| Purpose | Fix discrepancies between the current codebase and CLAUDE.md | Incorporate lessons learned during the session |
| When to trigger | After the codebase changes | Toward the end of a session |
| When to use | For periodic maintenance | When you realize "I should have written this down" |
claude-md-improver is a skill that surveys the entire codebase and audits whether your CLAUDE.md properly reflects the current code. Think of it as a regular health checkup.
/revise-claude-md, on the other hand, is more day-to-day: it's a command for capturing commands and pitfalls discovered during today's session directly into CLAUDE.md on the spot. You might think of it as the "note-taker."
Both tools ask for your approval before applying any edits, so there's no risk of your CLAUDE.md being rewritten without your knowledge.
Installation
The claude-plugins-official marketplace is automatically enabled when you launch Claude Code, so no additional setup is required. Just run the following inside Claude Code to install:
/plugin install claude-md-management@claude-plugins-official
If you'd like to browse and choose from available plugins, type /plugin and open the Discover tab, where you can search and install from the catalog.
After installation, don't forget to run /reload-plugins. This applies the skills and commands to your current session.
Usage 1: Auditing with claude-md-improver
Since claude-md-improver is a skill, you don't need to memorize a specific slash command. Just ask Claude in natural language and it will activate.
Please audit my CLAUDE.md
check if my CLAUDE.md is up to date
A single sentence like this is enough. Once the skill kicks in, the following workflow runs:
- Finds all
CLAUDE.mdandCLAUDE.local.mdfiles in the repository - Scores each one across six criteria and assigns a grade from A to F
- Presents a report with specific improvement suggestions
- Asks for your approval before applying the actual diff
For what it's worth, I personally type /claude-md and claude-md-improver appears as a suggestion, so I press Tab to expand it into /claude-md-management:claude-md-improver and run that.
The six scoring criteria
Scoring is based on a proper rubric, totaling 100 points.
| Criterion | Points | What it evaluates |
|---|---|---|
| Commands / Workflows | 20 | Whether build / test / lint / deploy commands are covered |
| Architecture Clarity | 20 | Whether directory structure and module relationships are clear |
| Non-Obvious Patterns | 15 | Whether pitfalls and project-specific quirks are documented |
| Conciseness | 15 | Whether it's bloated with redundant or obvious information |
| Currency | 15 | Whether it's consistent with the current codebase |
| Actionability | 15 | Whether commands can be copy-pasted and steps are concrete |
What's interesting is that Conciseness has a dedicated point allocation. "Just write everything down to be safe" is actually grounds for a deduction. Since CLAUDE.md is loaded as part of the prompt every session, more volume isn't necessarily better.
Results are displayed on a five-tier scale from A (90–100) to F (0–29). When I run this skill myself, I'm often surprised to get B or C grades, which drives home just how poor the quality of my CLAUDE.md had been—and how valuable this plugin really is.
Usage 2: Capturing lessons with /revise-claude-md
After a coding session, do you ever think, "I didn't know about that command," or "That directory structure isn't immediately obvious"? The command for passing those insights on to Claude in your next session is /revise-claude-md.
/claude-md-management:revise-claude-md
All plugin skills are called with their namespace prefix. If you type /claude-md-management:, Tab completion kicks in, so it's easier than it sounds.
When you run this command, Claude looks back over the current session and searches for "things worth writing down" from the following angles:
- Bash commands used or discovered
- Code style patterns followed
- Testing approaches that worked
- Environment or configuration quirks
- Pitfalls or warnings encountered
It then decides which CLAUDE.md to write to: CLAUDE.md for team-shared information, CLAUDE.local.md for personal notes.
Suggestions are shown in diff format, and the actual file isn't changed until you approve. If something feels too verbose, you can simply reject it—no risk of capturing too much.
CLAUDE.md has four homes
As you use this plugin, you'll notice that "CLAUDE.md" isn't just one thing. Let's clarify the different types.
| Type | Location | Purpose |
|---|---|---|
| Project root | ./CLAUDE.md | Team-shared. Committed to git |
| Local override | ./CLAUDE.local.md | Personal. Added to .gitignore |
| Global | ~/.claude/CLAUDE.md | Personal settings shared across all projects |
| Per-package | ./packages/*/CLAUDE.md | Module-specific info in a monorepo |
Claude Code automatically picks up CLAUDE.md files from parent directories and merges them, so placing a CLAUDE.md in each package of a monorepo (a setup where multiple packages live in a single repository) works without issue. This plugin audits each CLAUDE.md individually as well.
Best practices: how to grow your CLAUDE.md
Since we're here, let me also share the essence of "how to write a good CLAUDE.md" as gleaned from the plugin's update-guidelines.md.
What to write
- Commands you discovered: Commands like
npm run build:prodthat you had to look up on the spot—leave them for next time - Non-obvious patterns: Constraints like "tests must run serially with
--runInBand" that you can't figure out just from reading the code - Inter-package relationships: Dependencies like "the
authmodule must be imported aftercryptois initialized" - Testing approaches that worked: Established patterns like "use
supertestfor API tests" - Configuration quirks: Environment-specific notes like "Redis connections require
?family=0"
What not to write
- Things obvious from the code: Descriptions like "
UserServicehandles user operations" are self-evident from the class name - General advice: "Write proper tests" isn't project-specific information and isn't needed
- One-time fixes: "The bug fixed in commit abc123" won't recur, so writing it down is just noise
- Verbose explanations: Rather than explaining what JWT is from the RFC up, a single line like "Auth: JWT HS256,
Authorization: Bearer <token>" is enough
The key is to keep in mind that "CLAUDE.md is part of the prompt." Context window space is precious, so the right mindset is to demand "justification for inclusion" from every single line.
When to use which tool
Finally, let me recap how to choose between the two tools.
- After a major refactor or directory reorganization → Use
claude-md-improverfor a full audit - Right after introducing a new tool or configuration → Use
claude-md-improverto catch anything that wasn't reflected - When you think "oh, I didn't know that" during a session → Use
/revise-claude-mdto capture it on the spot
The recommended approach is to run both in tandem: regular health checkups (improver) and small daily captures (revise).
Conclusion
claude-md-management is a plugin that embodies the idea that "CLAUDE.md isn't something you write once and forget—it's something you grow." Being an official Anthropic release, it integrates well with Claude Code itself, and the setup cost was essentially zero.
Using it myself, I keep being surprised by how outdated my CLAUDE.md had become without my realizing it. If you use Claude Code on a regular basis, I highly recommend giving it a try. Even just having your CLAUDE.md audited will give you a slightly different perspective on your own project.