A Claude Code skill for maintainers, OSS evaluators, and anyone reviewing docs. It grades a README against an 8-axis rubric and returns a written, prioritized punch list.
Most READMEs fail because they document the surface (what the API looks like) instead of the mental model (what the system is, how it behaves, where it breaks).
Full rubric: SKILL.md.
When you invoke /judge-readme, Claude reads the README end-to-end and reviews it across:
- First-30-seconds test — can a stranger orient above the fold?
- 5-minute install — does pasting every code block in order produce a working thing?
- Reality match — do code samples compile, are limitations acknowledged?
- Navigability — TOC, section depth, cross-references, duplication
- Mental model — does it teach why, not just how?
- Progressive disclosure — can each audience stop at the section they need?
- Maintenance signals — changelog, license, CI badges, contribution path
- Honesty about limitations — gaps surfaced, not hidden
Then it applies two scoping heuristics — user contract ("can a new user ship a small correct integration cold?") and contributor contract ("can a new contributor ship a small correct PR cold?") — and returns a verdict, anti-pattern hits, and a prioritized fix list.
Prerequisites: Claude Code installed. Skills load automatically from ~/.claude/skills/; no restart needed.
Clone into your skills directory:
git clone https://github.com/techiejd/claude-skill-judge-readme.git ~/.claude/skills/judge-readmeOr grab just SKILL.md with curl:
mkdir -p ~/.claude/skills/judge-readme && \
curl -fsSL https://raw.githubusercontent.com/techiejd/claude-skill-judge-readme/main/SKILL.md \
-o ~/.claude/skills/judge-readme/SKILL.mdTo update later: cd ~/.claude/skills/judge-readme && git pull (clone install only).
Point Claude at any README in a project you're working in:
Review the README in this repo.
/judge-readme
You should see output shaped like:
Verdict: Strong on install, weak on mental model. A new user ships in 10 min;
a new contributor can't.
Section-by-section findings
1. First-30-seconds test — ...
...
Anti-patterns hit
- Quick Start ends without "verify it works" snippet (line 42)
User contract: PASS
Contributor contract: FAIL — no CONTRIBUTING.md and no architecture notes
Punch list
1. Add a "Verify it works" snippet after Install ...
If you get a generic praise-and-suggestion blob without the rubric structure, the skill didn't load — re-check the directory path.
In any Claude Code session, point at the README and invoke:
Review the README in this repo.
/judge-readme
You'll get back: verdict, section-by-section findings with line/heading references, anti-patterns hit, user and contributor contract pass/fail, and a prioritized punch list.
- Before publishing a public repo
- After a large doc rewrite, to catch regressions
- Evaluating an OSS dependency you're considering adopting
- Whenever you're tempted to ask "is this README good enough?"
- Verdicts are model-generated and may vary between runs. Treat the output as a strong second opinion, not a deterministic score.
- Grades the README only. Doesn't audit docs sites,
CONTRIBUTING.md, code comments, or external links — even when the README points at them. - English-language READMEs only. Other languages may work but the rubric and anti-pattern detection were tested in English.
- Doesn't fetch external resources. Won't verify that a CI badge actually reaches a passing pipeline or that a linked doc-site is alive.
Stars are the signal I use to decide whether to keep investing in a skill. If judge-readme caught something you would've shipped otherwise, star the repo — it's the difference between this getting more rubric refinements and going stale.
The rubric lives in SKILL.md — that's the file to change. Open an issue first if you're proposing a new axis or a structural change; one-line wording fixes can go straight to a PR. When proposing a rubric change, include a sample README and the verdict shift it produces.