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.