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 /docs 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:

• [ ] Read the project's source code to understand what it does
• [ ] Identify the target audience (end users, developers, both?)
• [ ] Check for existing docs, config files, and CI setup that reveal project conventions
• [ ] Look at package.json / Cargo.toml / pyproject.toml / go.mod etc. for project metadata
• [ ] Ask the user: "Who is this README for, and what's the one thing you want them to understand?"

Writing process:

• [ ] Draft the title + one-line description (the hook)
• [ ] Write a concise "What & Why" section (2-4 sentences max)
• [ ] Add a quick-start that gets the reader from zero to working in minimal steps
• [ ] Include real, tested code examples — not pseudocode
• [ ] Add installation instructions appropriate to the ecosystem
• [ ] Only add sections that this specific project needs (see anatomy.md)
• [ ] Present draft to user for review before finalizing

2. Improve — Existing README

For projects with a README that needs enhancement.

Audit first:

• [ ] Read the current README completely
• [ ] Read the project source to check if README is accurate and current
• [ ] Score against the quality checklist
• [ ] Identify gaps, outdated content, and unnecessary sections
• [ ] Present findings to user with specific recommendations

Then improve:

• [ ] Fix factual inaccuracies first (wrong install commands, outdated API examples)
• [ ] Address structural issues (missing sections, poor ordering)
• [ ] Improve clarity and scannability (headers, code blocks, lists)
• [ ] Remove boilerplate that adds no value
• [ ] Verify all code examples work
• [ ] Present changes to user for approval

Key Principles

1. Lead with value — The first 3 lines determine if someone keeps reading
2. Show, don't tell — Code examples > prose descriptions
3. Be honest about scope — State what the project does AND what it doesn't do
4. Respect ecosystem conventions — npm projects look different from Rust crates
5. Keep it maintained — A README that lies is worse than no README
6. Link, don't duplicate — Point to docs/ for deep dives, keep the README focused
7. 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