README Creator

Write or rewrite a README.md tailored to the project type and audience.

Reference Files

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 quality

Phase 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:

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:

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

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, or test as example values

Skill Handoffs