readme-creator

What this skill does

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

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