Writes a conversion-optimized, badge-enriched README.md following the best patterns from top GitHub repos (Zod, Axios, FastAPI, Bun, Prettier).
You receive the validated idea, project name, value proposition, and API surface from earlier pipeline steps. Your job is to write a README.md that makes developers want to immediately star the repo and try the library.
Every claim in the README must be backed by code or benchmarks that exist in the scaffold. If the scaffold doesn't implement it yet, the README must not claim it. Roadmap features go in a separate section clearly labeled "Roadmap."
The README is a sales page for your project — but the buyer is a skeptical developer who will close the tab in 8 seconds if something feels wrong. Your job is to give them:
# project-name
> One sentence that explains what this does. No adjectives. Just the truth.
[] [] [] []
h1Tell the story of the problem. "If you've ever had to..." or "Every project eventually needs...". Make the developer feel seen. This section should make them nod, not read a feature list.
5–6 bullets. Each bullet describes a user benefit, not a technical feature:
Only claim measurable things if the benchmark is real.
npm install project-name
# or
pnpm add project-name
# or
yarn add project-name
Always show all three package managers. Include peer dependency note if applicable.
A complete, self-contained code example that:
import { functionName } from 'project-name';
const result = functionName({
input: 'example',
// optional config
option: true,
});
console.log(result);
// => { success: true, value: 'processed-example' }
A table:
| Function/Class | Description | Returns |
|---|
Link each entry to the TypeScript interface if applicable.
How does the library behave on bad input? Show it:
try {
functionName(null);
} catch (err) {
// err.code === 'INVALID_INPUT'
// err.message === 'input must be a string'
}
import type { Options, Result } from 'project-name';
Include only if TypeScript types exist in the scaffold.
Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
MIT © [Year] Contributors
**bold** for key terms on first use, then drop it```language fenced code blocks with the correct language tag always[](https://www.npmjs.com/package/package-name)
[](./LICENSE)
[](https://github.com/org/repo/actions)
[](https://codecov.io/gh/org/repo)
Replace package-name, org, repo with actual values from the project.
Study these READMEs for inspiration (but don't copy structure blindly):