write-readme

Files (4)

• REFERENCE.md
• SKILL.md
• evals.json · evals/
• README.template.md · templates/

SKILL.md (first lines)

# write-readme

## Quick start

1. Ask the user for the **project name**, a **one-sentence tagline**, the **hero emoji** (🛡️ packages, 🏗️ infrastructure, 📚 docs, 🧰 tooling, etc.), and a **representative code snippet** (the "hook").
2. Copy `templates/README.template.md` and fill the placeholders.
3. Add only the sections the project actually needs — but keep them in the canonical order and use the prescribed emoji.
4. Show the draft and ask which optional sections to add/drop before writing the file.

## Canonical structure (always in this order)

| #   | Section            |   Emoji   | When to include                                                      |
| --- | :----------------- | :-------: | :------------------------------------------------------------------- |
| 1   | Hero block         | (project) | Always — `<div align="center">` + `# {emoji} {name}` + bold tagline. |
| 2   | Badges             |     —     | Only for public packages (Packagist / npm / CI / license).           |
| 3   | Hook               |     —     | Always — fenced code block + a single "That's it. …" sentence.       |
| 4   | Installation/Stack |    📦     | Always (label "Installation" for packages, "Stack" for infra/apps).  |
| 5   | Quick start/Setup  |    🚀     | Always (label "Quick start" for packages, "Setup" for infra/apps).   |
| 6   | Features           |    ✨     | Always — bullet list, each bullet `**{emoji} Title** — body.`        |
| 7   | Domain sections    |  varies   | As many as needed; pick emoji from the catalogue in REFERENCE.md.    |
| 8   | Contributing       |    🤝     | If the repo accepts external PRs.                                    |
| 9   | Versioning         |    🛣️     | Always — link to CHANGELOG.md and release-please.                    |
| 10  | License            |    📄     | Always — link to LICENSE + author/org line.                          |

> [!NOTE]
> **Installation / Quick start lead, then Features** — surfacing the install/run command near the top lets a reader reach it in ~30 seconds. Merging Installation + Quick start into a single **Install & run** section is acceptable (and is what `compact-readme` produces from a scaffolded file).

## Style rules

- **Hero** is wrapped in `<div align="center">…</div>`, followed by `---`.
- **Tagline** is one line, bold, em-dashes for emphasis. No period unless it's a full sentence.
- **Hook** uses a real, copy-pasteable snippet — the most representative thing the project does in 1–6 lines. Follow with one sentence ending in "That's it. …" pattern.
- **Feature bullets**: `- **{emoji} Title** — sentence.` Emojis act as scannable column-1 indicators.
- **Tables**: left-aligned (`| :--- |`).
- **Callouts**: use `> [!TIP]`, `> [!IMPORTANT]`, `> [!NOTE]` — never plain blockquotes.
- **Never mirror a file the repo already ships.** A README's job is the shortest path from landing to running — not a second copy of `package.json`'s scripts, a schema's option table, an `.env.example`, or a workflow. Show the handful of values a newcomer needs, then link the file for the rest. A copied table is wrong at the next commit and nothing will tell you; the repo, not the README, is the source of truth.
- **License footer** — copy the closing footer verbatim from [`templates/README.template.md`](templates/README.template.md), the single source for the Versioning/License blocks and the `© …` author line. Never retype the author/license string by hand.

## Workflow

1. **Gather** — name, tagline, hero emoji, hook snippet, public-or-internal, list of needed domain sections.
2. **Draft** — fill `templates/README.template.md`; pick domain-section emojis from [REFERENCE.md](REFERENCE.md).
3. **Review** — present the draft, confirm which optional sections to keep, then write the file.
4. **Gap report** — see below.

## Gap report (mandatory final step)

After writing the README, end the turn with a short report naming what [REFERENCE.md](REFERENCE.md) **prescribes** but does not yet cover.

**Three kinds are reportable, and nothing else.** They mirror REFERENCE.md's three prescriptive tables one for one — a gap is a hole in a table that _binds_, so what the skill does not prescribe cannot have one. There is deliberately **no catch-all line**: a fourth kind arrives only when the skill grows a fourth prescriptive table, and gains its report line in that same change.

- **Hero-emoji gaps** — you fell back to 📦 because no project type in the hero table matched.
- **Sections without a prescribed emoji** — an H2 you had to invent an emoji for because it isn't in the section catalogue.
- **Badges without a palette color** — a badge _purpose_ that fits none of `primary` / `neutral` / `success` / `laravel` / `php` / `node` / `warning`.

Two things look like gaps and are not:

- **Feature-bullet emojis are free-form — never report one.** REFERENCE.md's `Feature-bullet emojis` table says so itself: it is a suggestion list, not a catalogue, so an emoji it doesn't list is the table working as designed, with nothing to fold back in. Borrowing one from the section catalogue is fine too — the two already overlap on 🏢, 🧪, 🔍, 🧩 and 🗂️.
- **A missing badge _set_ is not a missing palette _color_.** The reportable case is a purpose with no token, never a project shape without a ready-made block under **Standard sets**. A public package that hasn't reached the registry yet takes the standard npm set unchanged — that is the decision, not a gap in it.

Format:

```text
Gap report — improvements for write-readme:
- Hero type "{description}" — no catalogue entry; used {emoji}.
- Section "{name}" — no catalogue entry; used {emoji} as ad-hoc choice.
- Badge "{purpose}" — no palette token; used color={hex}.
```

If everything was covered, say so: `Gap report: no gaps — every section and badge matched the catalogue.`

**Only report; do not edit REFERENCE.md or this skill yourself.** The user decides whether to fold the gaps back in.

<skills-plan>

## Presenting the plan

Everything this skill puts in front of a human — plan, preview, candidate list, findings report —
is read **once, in a terminal**, and answered there. So **every section of it renders on arrival**,
with no interaction needed to reveal it: prose, lists, tables, fenced code.

**Never fold content behind a control.** `<details>`/`<summary>` is a browser widget, and a
terminal has no way to open it: the summary line prints and everything under it does not. The plan
then arrives as headings with nothing beneath them, and the failure is silent on **both** sides —
the skill believes it reported, and the reader sees no marker saying anything is missing, so a
human confirms a plan whose contents never reached them. What gets folded is whatever ran long,
which is to say the part the decision actually rested on. The same holds for anything else needing
a click: a tab strip, an accordion, a "show more".

**Length is handled by shortening, never by hiding.** This is a fixed rule of the skill, not a
per-run judgement, so it holds however long the list runs. Trim to what the decision needs, group
the rest by something the reader already thinks in (ecosystem, kind, verdict) with a count per
group, or split it across sections. What is left out is left out **visibly**: say how many, why,
and the exact command that shows the rest.

**This binds what the skill presents, not what it writes.** A `<details>` block inside a README, an
issue body, a pull request description or a docs page is rendered by a browser and is entirely
legitimate there. The rule is about the message a human reads to decide — never about the content
of a file.

</skills-plan>

## Guardrails

- **Plan first; write only after confirmation** — the draft and its optional sections are agreed before the file lands (Workflow step 3).
- **Keep the generated README attribution-free** — no agent self-naming, no `Generated with`/🤖 line, no session URL. A README is the project's front door, not a record of who wrote it.
- **No secrets** — the hook is real, copy-pasteable code: scan it for tokens, keys and `.env` values, and show a placeholder rather than a live one.
- **Only the requested action** — this skill owns `README.md`. It never edits the files the README links to, and never commits.

## Reference

- **Open it the moment a hero, a section, a feature bullet or a badge needs its house-style value.** Every one of them is a catalogue lookup, never a choice a run makes for itself — a guessed emoji or an invented badge colour is exactly the drift this skill exists to prevent: [REFERENCE.md](REFERENCE.md).
- **Copy this first and fill it in place** — the canonical section order is already in it: [templates/README.template.md](templates/README.template.md).

From TitusKirch/skills, MIT.

More from TitusKirch/skills