README Writer

Produce README.md files that help a reader decide, in under thirty seconds, whether the project is worth their time — and then help them use it successfully.

A good README is a conversion funnel: headline → understand → install → first success → deeper docs. Every section either moves the reader along that funnel or earns its keep in some other way (badges signal trust, license reassures lawyers). Sections that don't serve the reader get cut.

Workflow

Follow these steps in order. Don't skip the intake — a README written without knowing the project is a Mad Libs page of plausible nonsense.

1. Intake — learn the project before writing anything

Gather three kinds of information: what can be auto-detected, what must be asked, and what lives in the code.

Auto-detect by inspecting the repo. If you have filesystem access, look for: