Readme Creator

README Creator

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

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

Reference Files

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 the user anything. The type drives every later decision, so detect it from evidence, not assumption.

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

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

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

Ask the user only what the code cannot reveal:

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

If the user is unreachable, infer the "why" from the manifest description and code, and note the assumption at the top of your summary rather than blocking.

Phase 2: Select sections

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

Phase 3: Write sections

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

• The H1 is the project name. The one-liner sits directly below with no heading and states what the project does, not what it "is".
• Put the feature list above the fold (before Install) so a reader sees the value before any setup cost.
• Install shows the single fastest path first: npm install -g for CLIs, npm install for libraries, clone-and-run for apps.
• Usage gives 3 to 5 runnable examples, simplest first, with real values (never foo, bar, example, test).
• Every code block must run as-is after copy-paste. No pseudocode, no placeholder imports left behind.
• A first-time reader should get something running within 60 seconds of opening the file.
• Disclose progressively: basics in the README, advanced detail in linked docs.

Phase 4: Add badges

Skip this phase 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 directly under the title and one-liner, and cap at 4.

Phase 5: Validate

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

The Automatic Fail list in the checklist is the hard gate: a missing description, missing install/getting-started, leftover boilerplate (an unchanged create-next-app README), or a code example that cannot run all mean the README is not done, regardless of the 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, signals the type was guessed wrong and sends readers down a path that does not work.
• Skill-bundle and private-monorepo READMEs get no badges and no version column: there is no registry entry behind them, so the badge renders broken or stale.
• Stale install commands are the most common rewrite bug: copy the package name from the manifest name field, not from the old README, which 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 just restates the one-liner is noise; cut it or make each bullet add a capability the one-liner did not name.
• Do not add a table of contents to a README under 100 lines: it pushes the install command below the fold for no navigation benefit.
• Never ship the framework's default scaffold README (create-next-app, create-vite). Replace it wholesale; readers treat it as an abandoned project.

Related skills

Badges and Shields

Badges go directly below the title and one-liner. Only add badges for published projects with real CI and registry presence.

When to Add Badges

• Project is published to a package registry (npm, crates.io, PyPI)
• Project has CI that actually runs
• Maximum 4 badges; more than that adds noise without value

When NOT to Add Badges

• Private or unpublished projects
• Projects without CI pipelines
• Web apps that are not packaged for distribution
• Skill bundles (unless published to npm)

Recommended Badges by Registry

npm (CLI tools and libraries)

[![npm version](https://img.shields.io/npm/v/{{name}}.svg)](https://www.npmjs.com/package/{{name}})
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)

Rust crates

[![crates.io](https://img.shields.io/crates/v/{{name}}.svg)](https://crates.io/crates/{{name}})
[![docs.rs](https://docs.rs/{{name}}/badge.svg)](https://docs.rs/{{name}})
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Python (PyPI)

[![PyPI version](https://img.shields.io/pypi/v/{{name}}.svg)](https://pypi.org/project/{{name}}/)
[![Python](https://img.shields.io/pypi/pyversions/{{name}}.svg)](https://pypi.org/project/{{name}}/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Placement Styles

Centered (for strong brand presence)

Used by CLIs and icon libraries. Creates visual impact.

<h1 align="center">{{name}}</h1>

<p align="center">{{one-liner}}</p>

<p align="center">
  <a href="https://www.npmjs.com/package/{{name}}"><img src="https://img.shields.io/npm/v/{{name}}.svg" alt="npm version"></a>
  <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
</p>

Inline (for utilities and libraries)

Simpler, less visual weight. Badges sit below the markdown title.

# {{name}}

[![npm version](https://img.shields.io/npm/v/{{name}}.svg)](https://www.npmjs.com/package/{{name}})
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)

{{one-liner}}

Common Badge Set

Most projects need at most three:

README Quality Checklist

Run before finalizing a new or rewritten README. Score each applicable item.

Scoring: Yes = 1, No = 0, N/A = exclude from denominator. Target: all applicable items pass.

Structure (6 checks)

1. Title is the project name (not "About", "Introduction", or "Overview") 2. One-liner description appears directly below the title without a heading 3. Install section shows the single fastest path with a runnable command 4. Usage section includes at least one copy-pasteable, runnable example 5. Sections follow the order from the project-type template 6. Table of contents present if the README exceeds 100 lines

Content (7 checks)

7. A new reader can install and run something within 60 seconds of reading 8. Every code block is copy-pasteable and runnable without modification 9. No placeholder text, TODO markers, Lorem ipsum, or foo/bar/example values 10. Description answers "what does this do" in one sentence 11. Install command includes the package manager and exact package name 12. Usage examples use realistic values and produce visible results 13. Requirements section lists minimum runtime version and system dependencies

Writing (5 checks)

14. Active voice throughout ("Install the package" not "The package can be installed") 15. No "This project is..." or "This is a..." openers 16. Consistent terminology (one term per concept, same casing throughout) 17. No orphaned sections (every heading has content below it) 18. License section present with license name and link to LICENSE file

Freshness (4 checks)

19. Badge versions match the actual published version (or badges are absent) 20. Install command uses the correct, currently published package name 21. Spot-check 2-3 links to confirm they are not broken 22. No references to deprecated APIs, removed features, or old package names

Project-Type Specific

CLI tools

• --help output matches the documented options
• Examples show real commands that produce expected output

Libraries

• API section covers all public exports
• Import paths match the actual package structure

Web apps

• Getting Started instructions produce a running app
• Environment variables table lists all required variables

Monorepos

• Packages/workspaces table lists every workspace in the project
• Version badges (if present) are not stale; skip badges entirely for private monorepos
• Multi-runtime setup steps are documented (e.g., Python venv, Rust toolchain)

Automatic Fail

Any of these means the README is not ready:

• No description (reader cannot tell what the project does)
• No install or getting started instructions (reader cannot use the project)
• Default boilerplate README (e.g., unchanged create-next-app template)
• Code examples that cannot run (syntax errors, missing imports, wrong API)

Section Templates

README skeletons for each project type. Copy the relevant template, fill placeholders, and adapt to the project.

Contents

• CLI tool
• Library / package
• Web app
• Framework
• Monorepo
• Skill bundle
• Section-by-section guidance

---

CLI Tool

<h1 align="center">{{name}}</h1>

<p align="center">{{one-liner}}</p>

<p align="center">
  <a href="https://www.npmjs.com/package/{{name}}"><img src="https://img.shields.io/npm/v/{{name}}.svg" alt="npm version"></a>
  <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
</p>

- **Feature one:** short explanation.
- **Feature two:** short explanation.
- **Feature three:** short explanation.

## Install

\`\`\`bash
npm install -g {{name}}
\`\`\`

Requires Node.js {{node-version}}+.

## Usage

\`\`\`bash
{{name}} {{basic-command}}
{{name}} {{command-with-flag}}
{{name}} {{command-with-options}}
\`\`\`

## Options

\`\`\`
-o, --output <file>    Description
-v, --verbose          Description
-h, --help             Show help
-V, --version          Show version
\`\`\`

## API

\`\`\`typescript
import { {{mainExport}} } from "{{name}}";

const result = await {{mainExport}}({{args}});
\`\`\`

## License

[MIT](LICENSE.md)

Notes

• Lead with the centered title + one-liner + badges block for visual impact.
• Feature list goes above the fold (no heading needed, just a bullet list).
• Show npm install -g first (global install for CLIs), then npx as alternative if applicable.
• Usage section: 3-5 real commands, simplest first. Show actual flags, not pseudocode.
• Options: copy from --help output. Keep formatting as a code block, not a table.
• API section: only include if the CLI also exports a programmatic API. Otherwise omit.

---

Library / Package

<h3 align="center">{{name}}</h3>
<p align="center">{{one-liner}}</p>

<p align="center">
  <a href="https://www.npmjs.com/package/{{name}}"><img alt="npm version" src="https://img.shields.io/npm/v/{{name}}"></a>
  <a href="LICENSE.md"><img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
</p>

## Highlights

- Highlight one
- Highlight two
- Highlight three

## Quick Start

\`\`\`bash
npm install {{name}}
\`\`\`

\`\`\`tsx
import { {{mainExport}} } from "{{name}}"

{{minimal-usage-example}}
\`\`\`

## Usage

\`\`\`tsx
// Pattern one
import { A } from "{{name}}"

// Pattern two (tree-shaking)
import { B } from "{{name}}/b"
\`\`\`

All components/functions accept these props/options:

- `option`: description (default: `value`)

## License

[MIT](LICENSE.md)

Notes

• "Highlights" instead of "Features": it's a library, so show what makes it stand out.
• Quick Start = install + minimal working example in under 10 lines total.
• Usage section shows import patterns and common configurations.
• Prop/option list uses inline code for names and defaults.
• Link to external docs site if one exists (add a Documentation section after Highlights).

---

Web App

# {{name}}

{{one-liner describing what the app does and who it's for}}

## Features

- **Feature one:** short explanation.
- **Feature two:** short explanation.
- **Feature three:** short explanation.

## Getting Started

\`\`\`bash
git clone https://github.com/{{owner}}/{{repo}}.git
cd {{repo}}
npm install
cp .env.example .env.local
npm run dev
\`\`\`

Open [http://localhost:3000](http://localhost:3000).

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | Database connection string | Yes |
| `API_KEY` | Third-party API key | Yes |

## Tech Stack

- [Next.js](https://nextjs.org/): framework
- [TypeScript](https://www.typescriptlang.org/): language
- [Tailwind CSS](https://tailwindcss.com/): styling

## License

[MIT](LICENSE.md)

Notes

• No badges for apps (they're not published to a registry).
• No centered title (apps are simpler, less "brand" presence).
• Getting Started replaces Install: readers need to clone and configure.
• Environment variables table is critical. Include .env.example in the repo.
• Tech Stack is optional but helps contributors understand the codebase.
• Never ship the default create-next-app README. Replace it immediately.

---

Framework

# {{name}}

[![npm version](https://img.shields.io/npm/v/{{name}}.svg)](https://www.npmjs.com/package/{{name}})
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)

{{one-liner explaining the core value proposition}}

## Features

- **Feature one:** detailed explanation of what it does and why it matters.
- **Feature two:** detailed explanation.
- **Feature three:** detailed explanation.

## Install

\`\`\`bash
npm install {{name}}
\`\`\`

## Quick Start

\`\`\`typescript
{{minimal-working-example}}
\`\`\`

## Usage

### Basic

\`\`\`typescript
{{basic-usage}}
\`\`\`

### Advanced

\`\`\`typescript
{{advanced-usage-with-configuration}}
\`\`\`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option` | `string` | `"default"` | What it controls |

## Requirements

- Node.js {{version}}+
- {{other-dependency}}

## License

[MIT](LICENSE.md)

Notes

• Feature descriptions are longer than for CLIs and libraries: explain the "why" alongside the "what".
• Progressive disclosure: Quick Start (5 lines) → Basic Usage → Advanced Usage → Configuration reference.
• Configuration table with types and defaults is essential for frameworks.
• Requirements section is more important here: frameworks often have specific runtime needs.

---

Monorepo (published)

# {{name}}

{{one-liner}}

## Packages

| Package | Description | Version |
|---------|-------------|---------|
| [`{{pkg-a}}`](packages/{{pkg-a}}) | What it does | [![npm](https://img.shields.io/npm/v/{{pkg-a}}.svg)](https://www.npmjs.com/package/{{pkg-a}}) |
| [`{{pkg-b}}`](packages/{{pkg-b}}) | What it does | [![npm](https://img.shields.io/npm/v/{{pkg-b}}.svg)](https://www.npmjs.com/package/{{pkg-b}}) |

## Getting Started

\`\`\`bash
git clone https://github.com/{{owner}}/{{repo}}.git
cd {{repo}}
npm install
npm run dev
\`\`\`

## Development

\`\`\`bash
npm run build       # Build all packages
npm run test        # Run all tests
npm run lint        # Lint all packages
\`\`\`

## Contributing

See individual package READMEs for package-specific setup.

## License

[MIT](LICENSE.md)

Notes

• The packages table is the centerpiece: it's how readers discover what's in the monorepo.
• Link each package name to its directory (which should have its own README).
• Version badges in the table give at-a-glance status for each package.
• Development commands run from root using the workspace tool (turbo, nx, etc.).

---

Monorepo (private / internal)

Use this when the monorepo is not published to a registry ("private": true in package.json, no npm publish). No badges, no version column. Focus on getting a contributor running fast.

# {{name}}

{{one-liner}}

## Requirements

- Node {{node-version}}+ (npm {{npm-version}}, see `packageManager` in `package.json`)
- {{additional-runtime}} (e.g., Python 3 for pipeline scripts)

## Quick start

\`\`\`bash
npm install
{{additional-setup-commands}}
npm run dev
\`\`\`

## Workspaces

| Package | Purpose |
|---------|---------|
| [`{{app-a}}`](apps/{{app-a}}) | What it does |
| [`{{pkg-a}}`](packages/{{pkg-a}}) | What it does |
| [`{{pkg-b}}`](packages/{{pkg-b}}) | What it does |

## Common commands

\`\`\`bash
npm run build            # build all workspaces
npm run typecheck        # type-check applicable workspaces
{{project-specific commands with inline comments}}
\`\`\`

{{optional: one paragraph on what is gitignored and why}}

Notes

• No badges, no version column: private packages have no registry presence.
• "Workspaces" instead of "Packages" reads clearer for mixed app + package monorepos.
• "Purpose" column instead of "Description" encourages specific, action-oriented text.
• Requirements section is critical when multiple runtimes are needed (Node + Python, Node + Rust).
• List setup commands for secondary runtimes in Quick start (e.g., npm run setup:python).
• Common commands section replaces "Development": show the commands people actually run, not generic build/test/lint.

---

Skill Bundle

# {{name}}

{{one-liner}}

## Quick Start

\`\`\`bash
npx skills add {{owner}}/{{repo}} -g --all -y
\`\`\`

Supports OpenCode, Claude Code, Codex, and Cursor. Install a single skill with `--skill <name>`.

## Skills

| Skill | Phase | What it does |
|-------|-------|-------------|
| `{{skill-a}}` | {{phase}} | {{description}} |
| `{{skill-b}}` | {{phase}} | {{description}} |

## Contributing

Edit the files in `skills/`. Keep `SKILL.md` concise and use reference files for detail.

Notes

• Quick Start is the single install command, nothing else needed.
• Skills table is the core content. One row per skill with phase and description.
• Contributing section is minimal: point to the skills/ directory.
• No license section needed if the bundle is not a published package (add one if it is).

---

Section-by-Section Guidance

Title

• Use the project name exactly as it appears in package.json name field (or equivalent).
• Never use "About", "Introduction", or "Overview" as the first heading.
• For published packages: centered HTML title (<h1 align="center">) or # name.
• For apps and internal tools: plain # name.

One-liner

• One sentence directly below the title. No heading.
• Answers: "What does this do?" in plain language.
• Bad: "This is a tool that helps you manage your configurations."
• Good: "Manage configurations across environments with type-safe schemas."

Feature list

• Bullet list with bold lead + short explanation.
• 5-9 features. More than 9 means you need subheadings or a docs site.
• Place above the fold (before Install) so readers see value before effort.
• Format: - **Feature name:** what it does. (not - **Feature name** - what it does.)

Install

• Show the single fastest path. For npm packages: npm install {{name}}.
• Add global flag for CLIs: npm install -g {{name}}.
• Show npx alternative only if it's the primary usage pattern.
• List requirements immediately after the install command (Node.js version, system deps).

Usage / Quick Start

• Start with the simplest possible example that produces a visible result.
• Every code block must be copy-pasteable and runnable without modification.
• Use realistic values. Never use foo, bar, example, or test as values.
• Show 3-5 examples. First is basic, last is advanced.
• For CLIs: show actual terminal commands with real flags.
• For libraries: show import + minimal usage in under 10 lines.

Options / API reference

• CLIs: paste --help output as a code block. Keep it as-is.
• Libraries: list exported functions/components with their signatures.
• Use tables for structured option docs (name, type, default, description).
• Only document public API. Internal functions stay internal.

Environment variables

• Table format: variable name, description, required/optional.
• Ship a .env.example file in the repo with placeholder values.
• Never include real API keys or secrets in examples.

License

• Always include. One line: [MIT](LICENSE.md) or equivalent.
• Use a link to the LICENSE file, not the full license text.