good-readme
Philosophy
Core principle: A README is the front door to your project. It should answer "what is this, why should I care, and how do I use it?" within 30 seconds. Every section earns its place by serving a reader's real need — don't pad with boilerplate.
Good READMEs are scannable, honest, and audience-aware. They lead with a clear value proposition, show real usage examples, and respect the reader's time. A developer evaluating your project will decide in under a minute whether to invest further — the README is your pitch.
Bad READMEs are walls of text with no structure, auto-generated boilerplate nobody reads, or sparse one-liners that force readers to dig through source code. Equally bad: over-documented READMEs that duplicate what's in
or include every API method inline.
See anatomy.md for section-by-section guidance, examples.md for patterns from well-regarded projects, anti-patterns.md for common mistakes, and cloudflare.md for Cloudflare ecosystem conventions.
Modes
This skill operates in two modes:
1. Create — New README
For projects that have no README or need one written from scratch.
Before writing anything:
Writing process:
2. Improve — Existing README
For projects with a README that needs enhancement.
Audit first:
Then improve:
Key Principles
- Lead with value — The first 3 lines determine if someone keeps reading
- Show, don't tell — Code examples > prose descriptions
- Be honest about scope — State what the project does AND what it doesn't do
- Respect ecosystem conventions — npm projects look different from Rust crates
- Keep it maintained — A README that lies is worse than no README
- Link, don't duplicate — Point to docs/ for deep dives, keep the README focused
- Test your examples — Broken code examples destroy trust instantly
Per-Section Checklist
[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions