readme-writinglisted

# README Writing The README is the **front door** of a project. Most readers arrive with one of three jobs: *decide if this is worth their time*, *get it running*, or *find one specific answer*. A good README serves all three in the order they appear — orientation first, action second, depth on demand. This skill is the deep reference for writing one: the required sections, the writing moves that make it scannable, the runnable-example discipline, and the failure modes that quietly drive readers away. Heavy detail lives in `references/`; copy-paste material in `examples/`; a runnable linter in `scripts/`. ## Mental model A README is read in **three passes**, and you write top-to-bottom to match them: | Pass | Reader's question | What answers it | |---|---|---| | Skim (10s) | "What is this and is it for me?" | Title + one-line description + badges | | Try (60s) | "Can I get it running?" | Install + minimal quickstart | | Use (later) | "How do I do X specifically?" | Usage, configuration, links to deeper docs | Optimize ruthlessly for the first 60 seconds. A reader who can't tell what the project does, or who hits a broken install command, leaves and does not come back. Everything else is recoverable; the first screen is not. ## The required sections (in order) A complete README has these, roughly in this sequence. Not every project needs every one, but you must make a deliberate choice to omit, never an accidental one. 1. **Title + one-line description** — what it is a