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

2. Discover evidence

Before drafting, gather facts from the tree that owns the README:

1. Manifests / lockfiles → package manager, scripts, runtime requirements
2. Entry points / public exports (libraries) or run/deploy commands (apps/services)
3. Existing docs to cross-link (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, docs/)
4. 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

1. Load references/section-checklist.md for required/optional sections by type.
2. Load only the matching template under references/templates/ when creating a new README or doing a major restructure.
3. Prefer surgical edits when syncing; don’t rewrite a healthy README for style alone.
4. Load references/writing-guide.md when prose quality, AI-tone cleanup, or example hygiene needs a pass.
5. 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

• Name + what/why + usage path present
• Install/run commands match lockfile / scripts / CI
• Quick Start leads with the interactive/happy path (flags under Non-interactive if needed)
• Examples are real or clearly marked as illustrative with verified APIs
• Links resolve; no invented features, deps, flags, or flag aliases
• Audience-appropriate sections only (checklist)
• Ask: anything else the reader needs that we missed?

Progressive disclosure

/update-readme is a thin Cursor wrapper that invokes this skill in update/sync mode.