README Writer
A README has one job: get a stranger from "what is this?" to "it's running" as fast as possible. Everything else is secondary.
Protocol
- Read the code before writing. The README must describe what the project actually does, not what you hope it does. Check the entry points, the public API, and the dependency manifest to ground every claim.
- Open with one sentence that says what it is and who it's for. No preamble, no "in today's fast-paced world". A reader decides in seconds whether to keep reading; earn it.
- Show, then tell. The first thing after the intro should be a concrete example: the smallest snippet that demonstrates the core value, copy-pasteable and correct. Verify it against the real signatures.
- Put installation and quickstart above the fold. The path from clone to running should be the most prominent section, with exact commands. Test that the commands work as written.
- Structure for scanning, not reading. Headings, short sections, one idea each. Assume the reader skims and jumps. The order that works: what it is, quickstart, core usage, configuration, then the deep material.
- Document the failure modes. Common errors and their fixes belong in the README, because that is where a stuck user looks first.
- Match the project's real maturity. A weekend project gets a short honest README. Do not fake enterprise polish, and do not bury a serious project under a toy one.
Never
- Never document features, flags, or commands that do not exist in the code.
- Never leave a quickstart you have not verified actually runs.
- Never open with a wall of badges and marketing before the reader knows what the thing is.
Done means
A stranger can read the top of the README and, within a minute, know what the project is, whether it fits their need, and how to get it running.
1---2name: readme-writer3description: Use when writing or overhauling a project's README. Produces a README that gets a project understood and used in under a minute, grounded in what the code actually does.4---56# README Writer78A README has one job: get a stranger from "what is this?" to "it's running" as fast as possible. Everything else is secondary.910## Protocol11121. **Read the code before writing.** The README must describe what the project actually does, not what you hope it does. Check the entry points, the public API, and the dependency manifest to ground every claim.132. **Open with one sentence that says what it is and who it's for.** No preamble, no "in today's fast-paced world". A reader decides in seconds whether to keep reading; earn it.143. **Show, then tell.** The first thing after the intro should be a concrete example: the smallest snippet that demonstrates the core value, copy-pasteable and correct. Verify it against the real signatures.154. **Put installation and quickstart above the fold.** The path from clone to running should be the most prominent section, with exact commands. Test that the commands work as written.165. **Structure for scanning, not reading.** Headings, short sections, one idea each. Assume the reader skims and jumps. The order that works: what it is, quickstart, core usage, configuration, then the deep material.176. **Document the failure modes.** Common errors and their fixes belong in the README, because that is where a stuck user looks first.187. **Match the project's real maturity.** A weekend project gets a short honest README. Do not fake enterprise polish, and do not bury a serious project under a toy one.1920## Never2122- Never document features, flags, or commands that do not exist in the code.23- Never leave a quickstart you have not verified actually runs.24- Never open with a wall of badges and marketing before the reader knows what the thing is.2526## Done means2728A stranger can read the top of the README and, within a minute, know what the project is, whether it fits their need, and how to get it running.
dkenge123-oss