Anthropic shipped a Claude Code plugin called claude-md-management. It grades your CLAUDE.md against six criteria, hands back a score out of 100 and a letter grade, and then offers to fix what it found. I pulled the scoring rubric and held it up against the CLAUDE.md that runs this blog. The file came in at 117 lines, comfortably under the 200-line target in the docs, and one single section was eating 43% of the characters in it (measured 5 August 2026).
Rules files are easy to ignore. Nothing runs them, no test covers them. But they get read in full at the start of every session, so a wrong line in there isn’t wrong once. It’s wrong every time.
What does the plugin actually do?
Two things, pointed in opposite directions. One grades the file you already have. The other collects new material for it.
The grader is a skill called claude-md-improver. Ask it to “audit my CLAUDE.md files” and it walks the repo for every CLAUDE.md and .claude.local.md, then prints a per-file table of scores before touching anything. The skill file spells that out in capitals: always output the quality report before making any updates. Edits come after, shown as diffs, applied only to what you approve.
The other half is a slash command, /revise-claude-md. You run it at the end of a working session and it looks back over what just happened. Commands you discovered, patterns you followed, environment quirks that bit you. Then it drafts a line to add. Its own instruction file puts the bar plainly: keep it concise, one line per concept, because CLAUDE.md is part of the prompt and brevity matters.
Installing takes one line.
/plugin install claude-md-management@claude-plugins-officialPer the plugin docs, the claude-plugins-official marketplace registers itself the first time you start Claude Code interactively. If it isn’t there, add it with /plugin marketplace add anthropics/claude-plugins-official and try again. You can also browse the catalog at claude.com/plugins.
What are the six criteria?
Here they are with the point values from the rubric file, which add up to exactly 100.
| Criterion | Points | The question it asks |
|---|---|---|
| Commands and workflows | 20 | Are build, test and deploy commands written down? |
| Architecture clarity | 20 | Can the codebase layout be understood from this? |
| Non-obvious patterns | 15 | Are the gotchas and quirks captured? |
| Conciseness | 15 | Any filler, or lines that restate the obvious? |
| Currency | 15 | Does this match the code as it stands today? |
| Actionability | 15 | Can the instructions be copy-pasted and run? |
Grades run A at 90 and up, B in the 70s and 80s, C in the 50s and 60s, D in the 30s and 40s, F below 30. The rubric also carries a red-flag list worth reading on its own: commands that would fail, paths pointing at deleted files, outdated versions, template text nobody customised, generic advice with nothing project-specific in it, TODOs that never got done, and the same information duplicated across several rules files.
So is keeping it short the main thing?
No, and the point values say so out loud. The two 20-point criteria are commands and architecture. Conciseness sits at 15, and in the skill’s own weighting column it’s one of only two marked Medium rather than High.
That surprised me. Conversations about rules files nearly always drift toward “it’s too long,” yet the rubric Anthropic wrote spends only 15 of 100 points there. Halve your file and the missing build commands are still a 20-point hole.
Length does matter, just not as the headline. The CLAUDE.md documentation is direct about it: target under 200 lines per file, because longer files consume more context and reduce adherence. The very next item is about contradictions, and it’s the one I’d pin above my desk. If two rules contradict each other, Claude may pick one arbitrarily. Not flag it, not ask. Pick one.
Scoring my own file
Numbers first. The CLAUDE.md for this blog’s repo is 117 lines, 12,921 characters, 21,854 bytes as of 5 August 2026.
| What I measured | Result |
|---|---|
| Lines | 117 (target is under 200) |
| Characters | 12,921 |
| Largest single section | 5,602 characters, or 43% of the file |
| Real file paths referenced | 30 |
| Paths that still exist | 30 |
By line count it passes with room to spare. By character count it doesn’t, because the average line runs 110 characters. A 200-line ceiling flatters a file written in long prose lines, and mine is exactly that kind of file.
The paths came out cleaner than I expected. I pulled every backticked path out of the file and checked each one for existence, skipping the placeholder patterns. All 30 real ones were still there. Nothing to report against the “paths pointing at deleted files” flag.
Then what was wrong with it?
A number I was keeping by hand. A line in the status section said the blog had 5 published posts. On 30 July 2026, when someone finally looked, the real count was 23. It had been wrong by 18 posts for weeks.
This is the part I keep thinking about. Everything a script can count was right. The one thing no script goes and counts was wrong. A file path either resolves or it doesn’t, which makes it cheap to verify. A sentence like “5 published posts” is grammatically fine and contradicts nothing else in the file. Reality just moves on quietly without it.
The fix wasn’t to update the number. It was to delete the number. That line now says the post count lives in content/post_YYYYMM.md and points there. A counter maintained by hand will drift, so the sentence stopped claiming a value it couldn’t keep. That’s the same test I used when writing about how to write requirements: can this sentence be counted, and can it be checked later?
How I manage the file now
Moving numbers stay out of it. Counts, versions, prices, anything that changes without the file changing gets replaced by a pointer to wherever the value actually lives. That rule came straight out of the miss above and it’s held since.
What goes in instead is the stuff the rubric puts 20 points on. Commands I actually type, how the folders are laid out, and the traps specific to this project. The most valuable paragraphs in my file are four server gotchas that no amount of reading the code would reveal, because they live in a hosting config I don’t own.
The duplication is still there. That 43% section restates rules that already exist in another document, which lands squarely on the last red flag in the list. I’m leaving it, at least for now. The cost of untangling it against the risk of cutting something load-bearing was weighed once already and the answer was to leave it alone. Having scored the file, I want to look at that decision again. The useful output wasn’t a grade, it was the second look.
Between paying for a bigger model and cleaning up what the model reads, the second one is cheaper and lands faster. When I built a dice game by vibe coding, the places I got stuck were never the model’s ceiling. They were the places where I hadn’t said what I wanted clearly enough.
What I’m not claiming
I didn’t install the plugin and run it. I fetched the rubric from the repository and applied it to my file by hand. That’s also why there’s no score in this post. A grade from the tool has to come from the tool.
I didn’t run the update phase either. The duplication in my file is a decision, not an oversight, so a set of proposed fixes would have nowhere to land.
One caution on plugins generally. The same docs carry a warning worth repeating: Anthropic doesn’t control what MCP servers, files or other software a plugin contains, and can’t verify that it works as intended. This one is Anthropic’s own, sitting in the internal plugins folder of the repository, but that same catalog lists third-party submissions too. The pile of AI tool names keeps growing, which I ran into while sorting out the current crop of AI buzzwords, and the habit of checking before installing has to grow with it.
Everything here, the point values and the install command, came from the repository and the official docs on 5 August 2026. Tooling docs move fast.