readme-creator

README Creator

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

• IS: writing a new or rewritten README.md, structured by detected project type (CLI, library, app, framework, monorepo, skill bundle), section by section.
• IS NOT: auditing or polishing an existing README's prose, or a multi-page docs site (use docs-writing); AGENTS.md or CLAUDE.md agent-instruction files (use agents-md). A README that already covers the project and just needs polish is docs-writing, not a rewrite.

Reference Files

File	Read when
references/section-templates.md	Phase 3: copy the matching skeleton and section guidance
references/badges-and-shields.md	Phase 4: only if publishing to a registry
references/quality-checklist.md	Phase 5: score before declaring done

Workflow

Copy this checklist to track progress:

README progress:
- [ ] Phase 1: Detect project type from manifests and structure
- [ ] Phase 2: Select sections for that type
- [ ] Phase 3: Write each section from the template
- [ ] Phase 4: Add badges (published projects only)
- [ ] Phase 5: Score against the checklist; record the pass count

Phase 1: Detect project type

Read the project before asking anything; the type drives every later decision, so detect from evidence.

Read the manifest (package.json, Cargo.toml, pyproject.toml, go.mod) for name, description, license, scripts, bin, and "private". Read the existing README if rewriting. Scan the top-level layout.

Classify into exactly one type. First matching row wins, top to bottom:

Type	Decisive signal
Skill bundle	skills/ dir of SKILL.md files
Monorepo (private)	workspace config (turbo.json, pnpm-workspace.yaml, workspaces) plus "private": true; no publish
Monorepo (published)	workspace config; packages published to a registry
CLI tool	bin field, src/cli.*, or commander/yargs/clap dep
Framework	plugin/middleware architecture, config API, documented extension points
Library / package	main/exports set, no bin, src/index.* entry
Web app	framework config (next.config.*, vite.config.*); no publish

If two types fit (a CLI that also exports an API, a framework published as a library), pick how most users consume it and fold the secondary role into one extra section.

Ask the user only what code cannot reveal:

• What problem does this solve (the "why" behind the one-liner)?
• Audience: end users, contributors, both?
• Any section to force in or leave out?

If unreachable, infer the "why" from the manifest and code, note the assumption in your summary, and proceed rather than block.

Phase 2: Select sections

Load references/section-templates.md. Use this matrix to pick sections (yes = include, opt = include if warranted, blank = omit):

Section	CLI	Library	App	Framework	Mono (pub)	Mono (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

Copy the matching skeleton from references/section-templates.md and fill it. The skeleton plus its Notes block carries per-type detail; these rules hold across every type:

• H1 is the project name. The one-liner sits directly below with no heading; state what it does, not what it "is". Good: "Manage configurations across environments with type-safe schemas." Bad: "This is a tool that helps you manage your configurations."
• Put the feature list above the fold (before Install) so value lands before setup cost.
• Install shows the fastest path first: npm install -g (CLIs), npm install (libraries), clone-and-run (apps).
• Usage gives 3 to 5 runnable examples, simplest first, real values (never foo, bar, example, test).
• Every code block runs as-is after copy-paste: no pseudocode, no leftover placeholder imports.
• A first-time reader gets something running within 60 seconds.
• Disclose progressively: basics in the README, advanced detail in linked docs.

Phase 4: Add badges

Skip entirely unless the project publishes to a registry (npm, crates.io, PyPI). Private apps, internal monorepos, unpublished skill bundles: no badges.

When badges apply, load references/badges-and-shields.md, place them under the title and one-liner, cap at 4.

Phase 5: Validate

Load references/quality-checklist.md. Score every applicable item, report the pass count as evidence; do not exit on "it reads fine". Fix every failed item, then reread top to bottom once to confirm flow.

Attach a render-check alongside the pass count: rg -n "foo|bar|TODO|\{\{" README.md must return nothing (no leftover placeholders or unresolved {{...}} mustaches). A non-empty result means not done.

The checklist's Automatic Fail list is the hard gate: missing description, missing install/getting-started, leftover boilerplate (unchanged create-next-app README), or a code example that cannot run. Any of these means not done, regardless of score.

Gotchas

• Detect the type before writing a line: a library README with a git clone Getting Started, or an app README with npm install/registry badges, means the type was guessed wrong and sends readers down a dead path.
• Skill-bundle and private-monorepo READMEs get no badges and no version column: no registry entry behind them, so badges render broken or stale.
• Stale install commands are the most common rewrite bug: copy the package name from the manifest name field, not the old README (it may predate a rename).
• Feature bullets use - **Name:** what it does. with a colon, never a hyphen separator (- **Name** - what it does. is the spaced-hyphen pattern this repo forbids).
• A "Features" section that restates the one-liner is noise: cut it or make each bullet add a capability the one-liner did not name.
• No table of contents in a README under 100 lines: it pushes install below the fold for no navigation benefit.
• Never ship a default scaffold README (create-next-app, create-vite): replace it wholesale; readers treat it as abandoned.

Related skills

When	Run
README exists and needs a prose audit, or a full docs site	docs-writing
Project needs agent instructions (AGENTS.md, CLAUDE.md)	agents-md