README Creator

Reference Files

references/section-templates.md

references/quality-checklist.md

references/badges-and-shields.md

README Workflow

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 quality

Phase 1: Discover project context

• 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.

bin

src/cli.ts

main

exports

src/index.ts

next.config.ts

vite.config.ts

turbo.json

pnpm-workspace.yaml

apps/

packages/

skills/

• What problem does the project solve? (the "why")
• Who is the target audience?
• Any sections to include or exclude?

Phase 2: Choose README structure

references/section-templates.md

Phase 3: Write sections

references/section-templates.md

• 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 -g

  for CLIs,

  npm install

  for libraries.
• Usage: 3-5 runnable examples, simplest first. Real values, not

  foo

  or

  example

  .
• 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

references/badges-and-shields.md

Phase 5: Validate quality

references/quality-checklist.md

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

  , or

  test

  as example values

Skill Handoffs

docs-writing

agents-md