README Creator
Write or rewrite a README.md tailored to the project type and audience.
Reference Files
| File | Read When |
|---|---|
references/section-templates.md | Phase 3: choosing structure and writing sections for a specific project type |
references/quality-checklist.md | Phase 5: validating the finished README against quality standards |
references/badges-and-shields.md | Phase 4: adding badges after the main content is written |
README Workflow
Copy this checklist to track progress:
README progress:
- [ ] Phase 1: Discover project context
- [ ] Phase 2: Choose README structure
- [ ] Phase 3: Write sections
- [ ] Phase 4: Add badges and extras
- [ ] Phase 5: Validate qualityPhase 1: Discover project context
Read the project before asking questions. Explore files to detect the project type:
- Read
package.json,Cargo.toml,pyproject.toml,go.mod, or equivalent for name, description, license, dependencies, scripts, and bin field. - Read existing README.md (if rewriting).
- Scan directory structure to understand architecture.
Classify into one of six project types:
| Type | Signals |
|---|---|
| CLI tool | bin field in package.json, src/cli.ts, commander/yargs dependency |
| Library / package | main/exports in package.json, no bin field, src/index.ts |
| Web app | next.config.ts, vite.config.ts, framework dependency, no npm publish |
| Framework | Plugin/middleware architecture, configuration API, extensibility points |
| Monorepo | turbo.json, pnpm-workspace.yaml, apps/ + packages/ directories |
| Skill bundle | skills/ directory with SKILL.md files |
Ask the user only for what cannot be discovered from the code:
- What problem does the project solve? (the "why")
- Who is the target audience?
- Any sections to include or exclude?
Phase 2: Choose README structure
Load references/section-templates.md.
Select sections based on the project type:
| Section | CLI | Library | App | Framework | Monorepo | Skills |
|---|---|---|---|---|---|---|
| Title + one-liner | yes | yes | yes | yes | yes | yes |
| Badges | yes | yes | -- | yes | yes | -- |
| Features / highlights | yes | yes | yes | yes | -- | yes |
| Install | yes | yes | -- | yes | yes | -- |
| Quick start / usage | yes | yes | yes | yes | yes | yes |
| Options / API reference | yes | yes | -- | yes | -- | -- |
| Configuration | opt | opt | yes | yes | opt | -- |
| Environment variables | -- | -- | yes | -- | -- | -- |
| Packages table | -- | -- | -- | -- | yes | -- |
| Skills table | -- | -- | -- | -- | -- | yes |
| Requirements | yes | yes | opt | yes | opt | -- |
| Contributing | opt | opt | opt | opt | opt | opt |
| License | yes | yes | yes | yes | yes | opt |
Phase 3: Write sections
Load references/section-templates.md. Write each section following the template for the detected project type.
Key principles:
- Title is the project name. One-liner directly below, no heading.
- Feature list above the fold (before Install) so readers see value before effort.
- Install: single fastest path first.
npm install -gfor CLIs,npm installfor libraries. - Usage: 3-5 runnable examples, simplest first. Real values, not
fooorexample. - Every code block must be copy-pasteable and runnable without modification.
- A reader should be able to install and run something within 60 seconds.
- Progressive disclosure: basic first, advanced later or in linked docs.
Phase 4: Add badges and extras
Load references/badges-and-shields.md. Add badges only if the project is published to a registry. Place directly below the title and one-liner. Maximum 4 badges.
Skip badges entirely for private apps, unpublished projects, and skill bundles.
Phase 5: Validate quality
Load references/quality-checklist.md. Run through every applicable check. Fix issues before finalizing.
After fixes, reread the README top to bottom to confirm it flows naturally.
Anti-patterns
- Do not write a README longer than the codebase warrants
- Do not include a table of contents for READMEs under 100 lines
- Do not use "About" or "Introduction" as the first heading
- Do not ship the default create-next-app or create-vite README
- Do not include badges for unpublished projects
- Do not include a "Features" section that restates the one-liner
- Do not write "This project is..." or "This is a..." — describe what it does directly
- Do not include empty Contributing or Acknowledgements sections
- Do not use
foo,bar, ortestas example values
Skill Handoffs
| When | Run |
|---|---|
| After README is written, audit prose quality | docs-writing |
| If project needs AGENTS.md / CLAUDE.md | agents-md |