A Claude Code skill that writes and reviews your README to a standard.
Every rule traces to a real source: the canonical guides, 20 top-tier READMEs, GitHub's docs, and 2025–2026 research on how agents read repos.
It's living. A research skill re-runs that survey and dates every change, so you always know what was verified.
- Cited, not vibes: every rule carries its evidence.
- Per project type: libraries, CLIs, web apps, APIs, research repos, tiny projects.
- Agent-ready: a skill generates or audits from the knowledge base, not memory.
- Refreshable: a maintainer skill re-researches and dates every change.
- Your voice: an optional style profile shapes tone while the cited rules keep it honest.
As a Claude Code plugin:
/plugin marketplace add albertogrande/readme-skill
/plugin install readme-skill@readme-skill
Or copy the skill into any project:
cp -r skills/readme /path/to/your-project/.claude/skills/No Claude? Read the knowledge base as plain markdown, starting with anatomy.md.
In any project with the plugin installed:
/readme-skill:readme generate # write a README for this repo
/readme-skill:readme review # audit the existing README, scored
The skill classifies your project, applies the matching template, and follows the rules. Bare-copy install uses /readme generate and /readme review.
review returns a scored report, not vague prose:
Score: 72 / 100 (Needs work)
Identity 15/15 · Trust 20/25 · Onboarding 12/25 · Structure 13/15 · Craft 7/10 · Agent 5/10
Top fixes (highest reader impact first):
1. ★ Install command errors: `npm i foo`, but the package is `@scope/foo` (Trust)
2. Usage example shows no expected output (Onboarding)
3. 9 badges in a scattered wall; 2 unlinked (Craft: badge wall)
…plus concrete replacement text for the worst offender.
The standard covers what's objective and sourced; voice and formatting are yours.
Drop a style profile at ~/.claude/readme-preferences.md (personal) or .claude/readme-preferences.md (one project), and the skill writes to it. Start from the template or the crisp example; details in preferences/about.md.
| File | What it answers |
|---|---|
| anatomy.md | Which sections, in what order, required per project type |
| section-guide.md | How to write each section, rule by rule |
| badges.md | Which badges earn a place, ordering, syntax, limits |
| checklist.md | The scored review rubric |
| anti-patterns.md | Named failure modes and how to fix them |
| ai-readers.md | README vs AGENTS.md vs llms.txt in the agent era |
| project-types.md | How to classify a repo and pick a template |
| sources.md | The annotated bibliography behind all of it |
Templates: library · CLI tool · web app · API/service · research/data · minimal
A maintainer-only /refresh-research skill re-runs the research, diffs it against the knowledge base, and updates only what changed. It bumps Last verified dates only for sources it actually re-fetched.
Every pass, including "nothing changed", lands in research/log/ and CHANGELOG.md. Scheduled automation is planned; see ROADMAP.md.
Does your README follow this standard? Add the badge:
[](https://github.com/albertogrande/readme-skill)Earn it honestly: run /readme review and clear the checklist with no critical failures.
Working on this repo? AGENTS.md has the non-obvious architecture rules. Indexing the docs? Start from llms.txt.
Issues and PRs welcome, especially pointers to sources the survey missed. A claim needs a citable source or a reproducible observation to enter the knowledge base.
MIT © Alberto Grande