GitHub README Generator
Write a README that makes people use your project: hook, quickstart, visuals, and honest docs.
The route
5 steps to Done
- 01
Write the hook section
The first screen decides if anyone keeps reading.
Preview prompt + verify gate ▾ Hide ▴
Write my README's opening. I will describe the project below. Produce: the project name with a one-line description (what it does, for whom); a 2-3 sentence 'why' (the problem and what makes this approach worth trying); a hero visual plan (screenshot/gif of the most impressive moment - specify what to capture); and 3-5 honest feature bullets (capabilities, not adjectives). Everything above the fold. MY PROJECT: [describe here]
- ✓ The one-liner says what it does
- ✓ Features are capabilities, not adjectives
- ✓ The hero visual is specified
- 02
Write the quickstart
From zero to running in minimal, tested steps.
Preview prompt + verify gate ▾ Hide ▴
Write the quickstart section: prerequisites with versions (runtime, package manager, services like a database); numbered install steps as copy-paste commands; configuration (env vars with an example file - document each variable's purpose); the run command and what success looks like (URL, expected output); and the fastest path to seeing the core feature work. Keep it to the minimum steps that truly work.
- ✓ Prerequisites include versions
- ✓ Every env var is documented
- ✓ Success criteria stated per stage
- 03
Write usage and examples
Show the main use cases with real, current code.
Preview prompt + verify gate ▾ Hide ▴
Write the usage section: 2-4 examples covering the main use cases, each with a short goal sentence, the exact command/code, and the expected result; an API/options reference if applicable (the important ones, not everything); and a troubleshooting sub-section with the 3 most likely failures and their fixes. All examples must reflect the CURRENT version's behavior.
- ✓ Each example has goal, code, and expected result
- ✓ Examples match current behavior
- ✓ Top 3 failure fixes included
- 04
Add project meta
Status, license, and contribution basics complete the trust picture.
Preview prompt + verify gate ▾ Hide ▴
Write the meta sections: honest project status (experimental/active/stable - and what is unfinished); a roadmap of 3-5 real next items; contribution notes (how to set up dev, how to submit changes, where to ask); license (choose and state one); credits/acknowledgements where due. Keep each section short and true - no aspirational governance for a solo project.
- ✓ Status matches reality
- ✓ The license is stated
- ✓ Contribution steps are minimal and real
- 05
Test the README cold
Follow it literally on a clean setup - fix every stumble.
Preview prompt + verify gate ▾ Hide ▴
Test the README: follow the quickstart literally on a clean environment (fresh clone, no cached config) and fix every step that fails or assumes knowledge; run every example and verify outputs; check all links and visuals render on GitHub; read the whole file top to bottom for flow and cut redundancy. Deliver the final README with a note of what the cold test caught.
- ✓ The quickstart was followed literally
- ✓ All examples ran
- ✓ Links and images render on GitHub