--- name: build-readme description: > Scaffolds a project's top-level README.md — the `README.md` at a repository root that orients a first-time reader in the top 30 seconds. Produces a conditionalized template with a single H1, one-sentence description, problem statement, badges block, H2 section sequence (Prerequisites → Installation → Usage → Configuration → Troubleshooting → Contributing → License), fenced code blocks with language tags, and placeholder discipline. Use when the user wants to "scaffold a README", "create a README", or "bootstrap README.md". Not for sub-package READMEs inside a monorepo, docs-site landing pages, or GitHub org-profile READMEs — those have different audiences and out of scope. argument-hint: "[project-name]" user-invocable: true references: - ../../_shared/references/readme-best-practices.md - ../../_shared/references/primitive-routing.md license: MIT --- # Build README Scaffold a project's top-level `README.md`: the first file a stranger sees after `git clone`, a dependency listing, or a package-registry page. The authoring rubric — what a good README does, the anatomy template, the patterns that work — lives in [readme-best-practices.md](../../_shared/references/readme-best-practices.md). This skill is the workflow; the principles doc is the rubric. **Scope is top-level only.** Sub-package READMEs inside a monorepo directory, documentation-site landing pages, and GitHub organization profile READMEs are out of scope and refused at the Scope Gate. They serve different audiences and deserve different rubrics. **Workflow sequence:** 1. Route → 2. Scope Gate → 3. Elicit → 4. Draft → 5. Safety Check → 6. Review Gate → 7. Save → 8. Test ## When to use Also fires when the user phrases the request as: - "write the project README" - "new README for this repo" ## 1. Route Confirm a top-level `README.md` is the right artifact before asking scaffold-specific questions. **Wrong artifact:** - **Package/module docstring, not a README** → author in the language's native docstring format; not this skill. - **A Claude Code skill or rule doc** → `/build:build-skill` or `/build:build-rule`. - **A changelog, contributing guide, or architecture doc** → those are sibling markdown files (`CHANGELOG.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`), not the README — the README *links to* them. **Wrong scope — recommend an alternative:** - **Sub-package README** (`packages/foo/README.md` in a monorepo) — the audience is a reader already in the repo, not a stranger; the rubric differs. Hand-write or propose a dedicated `/build:build-subpackage-readme` pair when demand justifies it. - **Docs-site landing page** — styled deliverable; the toolchain (Docusaurus, mkdocs, etc.) drives the shape. - **GitHub org-profile README** (`.github/profile/README.md`) — marketing surface, not a project entry point. **Right artifact and right scope** → proceed to Scope Gate. ## 2. Scope Gate Refuse to scaffold when any of these signal: 1. **An existing `README.md` is already present at the target path and non-trivial** (more than ~20 lines of real content, not a stub). Scaffolding over it would discard work. Offer instead to run `/build:check-readme ` and iterate from findings. 2. **No project context available** — the target directory has no discernible project (no `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `pom.xml`, or similar). A README for an empty directory is a template, not a README; ask the user to confirm they want a generic skeleton or to initialize the project first. 3. **Target is not a repository root** — the path given is several directories deep and is clearly a sub-package. Confirm scope (see Route §1); refuse sub-package READMEs. If any signal fires, state the signal, name the recommended alternative, and stop. Do not proceed to Elicit. ## 3. Elicit If `$ARGUMENTS` is non-empty, parse it as `[project-name]` and pre-fill question 1. Otherwise ask, one question at a time: **1. Project name** — the single H1. Typically the package name or repo name. Avoid marketing phrases; the H1 is for humans and tools. **2. One-sentence description** — what the project *is* (not what it does). "A Python library for X", "A CLI tool that X", "A service that X". This is the most-read line in the document. **3. Problem statement** — 2-3 sentences: what problem does this solve, who is it for. Features answer *how*; the problem statement answers *why I should care*. **4. Language / runtime + minimum version** — Node 18+, Python 3.10+, Go 1.22+, etc. Populates Prerequisites. **5. Install command(s)** — the command a reader would run on a clean machine. Include language identifier for the fenced block (`bash`, `sh`, `pwsh`). Multi-platform? List each with a labeled block. **6. Quickstart command + expected output** — the minimal runnable example. If the project is a library, show the smallest import + call that produces visible output. **7. Configuration surface** — environment variables, config files, or CLI flags the user must set before running. Omit if none (the scaffold drops the Configuration H2). **8. License** — SPDX identifier (MIT, Apache-2.0, GPL-3.0, etc.). Required; the scaffold refuses to omit the License section. **9. Distribution channel** — GitHub-only, or does this also ship to npm / PyPI / crates.io / similar? Determines relative-vs-absolute link default (relative for GitHub-only; absolute for package mirrors). **10. Badges to include** — CI status, package version, license, coverage. Cap at 5; more is scan-noise. Ask for URLs or accept "standard set for this stack" and propose defaults. **11. Save path** — default is `README.md` at the current working directory. Confirm. ## 4. Draft Produce a single conditionalized template. Sections marked *(if X)* are omitted when intake rules them out. ````markdown # ← Intake #1 ← Intake #2 <2-3 sentence problem statement> ← Intake #3 ← Intake #10 (if any) ## Prerequisites - ← Intake #4 - ## Installation ``` ← Intake #5 ``` ## Usage ``` ← Intake #6 ``` Expected output: ``` ``` ## Configuration ← (if Intake #7 non-empty) | Variable | Default | Required | Description | |----------|---------|----------|-------------| | `` | | yes/no | | ## Troubleshooting ← placeholder; one FAQ entry **Problem:** **Cause:** **Fix:** ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). ## License — see [LICENSE](LICENSE). ← Intake #8 ```` **Link style default:** - *(if Intake #9 = GitHub-only)* Use relative links (`CONTRIBUTING.md`, `LICENSE`). - *(if Intake #9 = package mirror)* Use absolute URLs (`https://github.com///blob/main/CONTRIBUTING.md`) and prompt for the repo URL. *(if Intake #7 = none)* Omit the entire Configuration H2. Present the draft plus a suggested `git add README.md` invocation line to the user before any safety checks. ## 5. Safety Check Review the draft against the rubric in [readme-best-practices.md](../../_shared/references/readme-best-practices.md) before presenting. Group the checks: **Structure.** Single H1 on first content line. One-sentence description on the next line. 2-3 sentence problem statement follows. H2 sequence in reader-intent order. Heading levels sequential (no H2 → H4 skips). **Commands & code blocks.** Every command block carries a language tag. No shell-prompt prefixes (`$`, `>`, `#`). Placeholders marked with `<...>`. Code-block lines ≤80 characters. **Safety.** No real secrets, tokens, credentials, or hostnames in the draft. No pipe-to-shell installers without a documented manual alternative. No destructive commands without a warning callout. Example domains/IPs are RFC-reserved only (`example.com`, `*.test`, `127.0.0.1`, RFC 5737 ranges). **Completeness.** License section present with SPDX identifier and link. Contributing section links to `CONTRIBUTING.md`. No `TODO` / `FIXME` / `XXX` markers in the draft. **Style.** Imperative mood for instructions ("Run `npm install`", not "You should run…"). No emoji in headings. Prose lines ≤120 characters. If any check fails, revise the draft before presenting. The Review Gate is for user approval, not correctness recovery. ## 6. Review Gate Present the draft (full README content + suggested `git add` invocation) and wait for explicit user approval before writing any file to disk. Write only after this gate passes. If the user requests changes, revise and re-present. Continue until the user explicitly approves or cancels. Proceed to Save only on explicit approval. ## 7. Save Write the approved README to the path elicited in Step 3.11 (default `README.md` at the current working directory). Do **not** `chmod +x` — markdown is data, not executable. Do not create sibling files (`LICENSE`, `CONTRIBUTING.md`); the README references them, but creating them is out of scope. Prompt the user to add those files separately if they are not yet present. ## 8. Test Offer the audit: > "Run `/build:check-readme ` to audit the scaffolded README > against structure, safety, completeness, and judgment dimensions?" The audit is the canonical follow-on; running it once after scaffold catches anything the Safety Check missed. ## Anti-Pattern Guards 1. **Omitting the License section** — even if the user does not yet have a LICENSE file, the section is required. The scaffold links to a LICENSE file that may not exist yet; that is the prompt to create it, not an excuse to skip the section. 2. **Scaffolding marketing language** — the H1 is the project name, not a tagline. The one-sentence description is what it *is*, not what it *promises*. Salesy language belongs on a landing page. 3. **Forgetting expected output in Quickstart** — the command alone is half the contract. Silence after a command breeds doubt. 4. **Shell prompts in code blocks** — `$ npm install` cannot be copy-pasted. Drop the prompt. 5. **Real secrets in examples** — even in a draft. Readers copy-paste before reviewers read. ## Key Instructions - Refuse cleanly on Scope Gate signals. Sub-package READMEs and existing non-trivial READMEs are hard refuses with alternatives named. - Write files to disk only after the Review Gate passes. - The License section is always scaffolded — it is not intake-gated. An SPDX identifier is elicited explicitly. - The Configuration H2 *is* intake-gated — omit when no config surface exists. Empty sections are scan-noise. - Code-block language tags are mandatory on every fenced block. Default to the target shell / language; never empty info-strings. - Use relative links by default; switch to absolute URLs only when Intake #9 flags package-mirror distribution. - Won't scaffold over a non-trivial existing README — offer `/build:check-readme` instead. - Won't inline real secrets, hostnames, or credentials in examples — use reserved ranges. ## Handoff **Chainable to:** `/build:check-readme` (audit the scaffolded README against structure, safety, completeness, and the seven judgment dimensions).