mblode/readme-creator

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 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 seven 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 (published) | turbo.json or pnpm-workspace.yaml, packages published to a registry | | Monorepo (private) | turbo.json or pnpm-workspace.yaml with "private": true, no registry publish | | 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 (pub) | Monorepo (priv) | Skills | |---------|-----|---------|-----|-----------|----------------|-----------------|--------| | Title + one-liner | yes | 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 | yes | | Options / API reference | yes | yes | -- | yes | -- | -- | -- | | Configuration | opt | opt | yes | yes | opt | -- | -- | | Environment variables | -- | -- | yes | -- | -- | -- | -- | | Packages / workspaces table | -- | -- | -- | -- | yes | yes | -- | | Skills table | -- | -- | -- | -- | -- | -- | yes | | Requirements | yes | yes | opt | yes | opt | yes | -- | | Common commands | -- | -- | -- | -- | opt | yes | -- | | Contributing | opt | opt | opt | opt | opt | opt | opt | | License | yes | yes | yes | yes | yes | opt | 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 -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

| When | Run | |------|-----| | After README is written, audit prose quality | docs-writing | | If project needs AGENTS.md / CLAUDE.md | agents-md |