README Authoring
Write READMEs that answer the reader’s next question — grounded in what the
repo actually does.
Principles
- Audience first — OSS users ≠ new hires ≠ future-you in a config folder.
- Evidence over invention — claims, commands, flags, and APIs must match files or the user’s stated surface. Do not invent short aliases (e.g.
-y) unless evidenced.
- Shortest path to working — one happy-path command early; flags and alternate installs below.
- Quick Start first viewport — prefer
## Quick Start; interactive/zero-flag path first; Non-interactive second (see references/quick-start-patterns.md for npm/CLI packages).
- Link, don’t duplicate — deeper docs stay linked.
- Human prose — direct, active voice; no promotional or inflated AI tone.
Procedure
1. Scope
| Clarify |
Options |
| Task |
Create · Add section · Update/sync · Review |
| Audience / type |
OSS · Internal · Personal · Config (ask if unclear) |
| README path |
Repo root or package dir (monorepo: scope analysis to that tree) |
2. Discover evidence
Before drafting, gather facts from the tree that owns the README:
- Manifests / lockfiles → package manager, scripts, runtime requirements
- Entry points / public exports (libraries) or run/deploy commands (apps/services)
- Existing docs to cross-link (
CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, docs/)
- Real usage:
examples/, tests, or documented CLI — never fabricate samples
Load references/evidence-discovery.md when the tree is large, monorepo-scoped, or the public surface is unclear.
3. Diff against current README (if any)
Present a short gap list before writing:
- Missing — real capability undocumented
- Stale — documented but gone / renamed / wrong commands
- Wrong audience — sections that don’t match project type
- Dense Quick Start — flag soup, three install stories, or jargon in the first viewport (npm/CLI)
4. Draft or patch
- Load
references/section-checklist.md for required/optional sections by type.
- Load only the matching template under
references/templates/ when creating a new README or doing a major restructure.
- Prefer surgical edits when syncing; don’t rewrite a healthy README for style alone.
- Load
references/writing-guide.md when prose quality, AI-tone cleanup, or example hygiene needs a pass.
- Load
references/quick-start-patterns.md when the package is a public npm CLI/scaffolder, or the install section is hard to scan.
5. Validate before done
Progressive disclosure
| Reference |
When to read |
references/section-checklist.md |
Choosing or auditing sections by project type |
references/evidence-discovery.md |
Large/monorepo trees, unclear entry points, sync audits |
references/writing-guide.md |
Prose cleanup, anti-patterns, example rules |
references/quick-start-patterns.md |
npm/CLI Quick Start density; Interactive vs Non-interactive shape |
references/templates/oss.md |
New or major OSS README |
references/templates/internal.md |
New or major internal/service README |
references/templates/personal.md |
Personal / portfolio project |
references/templates/config.md |
Dotfiles / config / “what’s in this folder” README |
/update-readme is a thin Cursor wrapper that invokes this skill in update/sync mode.
1---2name: readme-authoring3description: Create, update, review, or sync README.md files with evidence from the codebase, matched to audience (OSS, internal, personal, config). Use when writing or refreshing a README, documenting a package or CLI quick start, fixing stale/dense install docs, or when /update-readme is invoked. Do not use for changelogs, release notes, API reference generation, CONTRIBUTING-only or AGENTS.md-only edits, marketing landing copy, or optimizing Agent Skills.4---56# README Authoring78Write READMEs that answer the reader’s next question — grounded in what the9repo actually does.1011## Principles1213- **Audience first** — OSS users ≠ new hires ≠ future-you in a config folder.14- **Evidence over invention** — claims, commands, flags, and APIs must match files or the user’s stated surface. Do not invent short aliases (e.g. `-y`) unless evidenced.15- **Shortest path to working** — one happy-path command early; flags and alternate installs below.16- **Quick Start first viewport** — prefer `## Quick Start`; interactive/zero-flag path first; Non-interactive second (see `references/quick-start-patterns.md` for npm/CLI packages).17- **Link, don’t duplicate** — deeper docs stay linked.18- **Human prose** — direct, active voice; no promotional or inflated AI tone.1920## Procedure2122### 1. Scope2324| Clarify | Options |25|---------|---------|26| Task | Create · Add section · Update/sync · Review |27| Audience / type | OSS · Internal · Personal · Config (ask if unclear) |28| README path | Repo root or package dir (monorepo: scope analysis to that tree) |2930### 2. Discover evidence3132Before drafting, gather facts from the tree that owns the README:33341. Manifests / lockfiles → package manager, scripts, runtime requirements352. Entry points / public exports (libraries) or run/deploy commands (apps/services)363. Existing docs to cross-link (`CONTRIBUTING.md`, `AGENTS.md`, `ARCHITECTURE.md`, `docs/`)374. Real usage: `examples/`, tests, or documented CLI — never fabricate samples3839Load `references/evidence-discovery.md` when the tree is large, monorepo-scoped, or the public surface is unclear.4041### 3. Diff against current README (if any)4243Present a short gap list before writing:4445- **Missing** — real capability undocumented46- **Stale** — documented but gone / renamed / wrong commands47- **Wrong audience** — sections that don’t match project type48- **Dense Quick Start** — flag soup, three install stories, or jargon in the first viewport (npm/CLI)4950### 4. Draft or patch51521. Load `references/section-checklist.md` for required/optional sections by type.532. Load only the matching template under `references/templates/` when creating a new README or doing a major restructure.543. Prefer surgical edits when syncing; don’t rewrite a healthy README for style alone.554. Load `references/writing-guide.md` when prose quality, AI-tone cleanup, or example hygiene needs a pass.565. Load `references/quick-start-patterns.md` when the package is a public npm CLI/scaffolder, or the install section is hard to scan.5758### 5. Validate before done5960- [ ] Name + what/why + usage path present61- [ ] Install/run commands match lockfile / scripts / CI62- [ ] Quick Start leads with the interactive/happy path (flags under Non-interactive if needed)63- [ ] Examples are real or clearly marked as illustrative with verified APIs64- [ ] Links resolve; no invented features, deps, flags, or flag aliases65- [ ] Audience-appropriate sections only (checklist)66- [ ] Ask: anything else the reader needs that we missed?6768## Progressive disclosure6970| Reference | When to read |71|-----------|----------------|72| `references/section-checklist.md` | Choosing or auditing sections by project type |73| `references/evidence-discovery.md` | Large/monorepo trees, unclear entry points, sync audits |74| `references/writing-guide.md` | Prose cleanup, anti-patterns, example rules |75| `references/quick-start-patterns.md` | npm/CLI Quick Start density; Interactive vs Non-interactive shape |76| `references/templates/oss.md` | New or major OSS README |77| `references/templates/internal.md` | New or major internal/service README |78| `references/templates/personal.md` | Personal / portfolio project |79| `references/templates/config.md` | Dotfiles / config / “what’s in this folder” README |8081`/update-readme` is a thin Cursor wrapper that invokes this skill in **update/sync** mode.
rhyanvargas