--- name: compact-readme description: Compacts an existing, overstuffed README so the landing view leads to the install/run command in ~30 seconds, without losing any information — long feature walls and option tables move into
blocks, install+quickstart merge, and duplicated taglines/runtime-notes are deduped. Preserves the kirchDev house style (centered hero, emoji tagline, section emojis, Versioning/License closers). The complement to write-readme: write-readme scaffolds a new README from scratch; compact-readme slims down one that already exists. Use when a README is too long/dense/repetitive and the user wants it tightened, condensed, decluttered, or made scannable. Do not use to create a new README. allowed-tools: - Read - Write - Edit - Bash - Glob - Grep --- # compact-readme Take an existing README that has grown into a wall of text and tables, and tighten the landing view so a reader reaches the install/run command in ~30 seconds — while preserving every fact by relocating (never deleting) detail into `
` blocks and merged paragraphs. > [!IMPORTANT] > **This is the complement to [`write-readme`](../write-readme/SKILL.md).** `write-readme` = scaffold a new README from scratch in the kirchDev house style. `compact-readme` = slim down an _existing_ one. If there is no README yet, stop and use `write-readme` instead. > [!IMPORTANT] > **Never delete content.** Everything you cut from the visible view must land somewhere — folded into a `
` block or merged into an existing paragraph. The goal is fewer _visible_ lines, not less information. ## Goal & rule of thumb - The un-collapsed (visible, outside `
`) line count should roughly **halve**, with zero information loss. - Reference detail stays in the file, just collapsed or consolidated. - Reference: the envprism README went from ~194 → ~98 visible lines by folding the feature list + config tables into `
`, merging Install+Quickstart, and deduping the tagline / runtime note / "round-trip preserving" claim. See [REFERENCE.md](REFERENCE.md) for the worked before/after. ## Step 1 — Diagnose (measure before you cut) 1. **Read the whole README** and count total lines (`wc -l README.md`). 2. **Attribute the bulk** — which sections eat the most lines? Usual culprits: long feature bullet walls and big Configuration/Options tables. 3. **Spot redundancy**, e.g.: - the tagline restated in hero + hook + a later sentence, - a runtime/requirement note ("needs Bun, `npx` won't work") repeated across hero, install, and a callout, - a repeated core claim ("round-trip preserving", "zero-config") stated in several places. 4. **Check the house style** is intact (centered hero, section emojis, Versioning/License closers) — preserve whatever is already correct. Present the diagnosis (line count, biggest sections, redundancies found) and the planned cuts **before** editing — see [Interaction](#interaction). ## Step 2 — Transform Apply these, in roughly this priority: 1. **Feature list → ~8–10 real highlights + a `
` superset.** Trim the visible list to genuine highlights. Move implementation detail (regexes, internal parser rules, full theme/color-key lists, every single keybinding) out of the highlights. Put the **complete, categorized** list into `
Full feature list…
` as a superset — nothing is lost. 2. **Configuration/options → teaser + minimal example + `
`.** Keep a short teaser sentence and one minimal config example visible; collapse all option tables and theme/color keys into `
All configuration options…
`. Keep everything in **one file** — do not spin out to `docs/` unless the user explicitly asks. 3. **Merge Install + Quick start** into one "Install & run" section. State the runtime requirement **exactly once**, as a `> [!IMPORTANT]` callout in that block, including the concrete gotcha (e.g. "`npx` won't work"). 4. **Dedupe repeated claims** — pick the single best spot for each restated tagline / requirement / core claim and remove the echoes. 5. **Reduce bold density.** If every bullet is fully `**bold**`, nothing stands out. Bold only ~the first phrase of each bullet. 6. **Tighten prose** — e.g. a Why/Problem section from 3 paragraphs to 2 — but keep the author's voice; do not flatten it into generic AI slop. ## Step 3 — Target structure (order) ```text Hero (logo, tagline, badges, optional demo GIF) Hook (1 code line + ~2 sentences) 🤔 Why (problem → solution, tight) 📦 Install & run (merged; requirement callout ×1) ✨ Features (~10 highlights +
full list) [optional] 🧪 CI / scripting (short standalone block, if it deserves one) ⚙️ Configuration (teaser + example +
tables) 🤝 Contributing 🛣️ Versioning 📄 License ``` Use the prescribed section emojis from the [`write-readme` REFERENCE](../write-readme/REFERENCE.md#section-emoji-catalogue). ## Guardrails - **Never delete content** — relocate into `
` or merge into a paragraph. - **Preserve the house style strictly** — centered hero in `
`, section emojis, Versioning/License at the end. For kirchDev repos, treat [`write-readme`](../write-readme/SKILL.md) as the style source of truth. - **Leave these untouched**: badges, links, the demo GIF, and the license/author line. - **Factual accuracy** — never rewrite or invent defaults, flags, or option values. Copy tables **verbatim**; only move them. - **Formatter check** — if the repo has an oxfmt/Prettier config, confirm `README.md` is excluded from the formatter (kirchDev excludes it in `lint-staged.config.js`, because oxfmt reflows the centered hero and `
` markup). If it is **not** excluded, run the formatter after editing so you don't leave a diff CI will reject. - **Report visible-line delta** after the rebuild: before vs after (outside `
`), plus a short "what moved where" list. ## When not to / when to ease off - **Don't create new READMEs** — that's `write-readme`. - **If the README is already lean**, don't force structural surgery. Just smooth redundancy and bold density, and say so in the report. ## Interaction Before writing, show the **diagnosis + planned cuts**, then ask: 1. **Aggressiveness** — light / medium / aggressive. 2. **Full feature list** — collapse into `
` _(recommended default)_ / drop entirely / move to `docs/`. Then apply, and end with the before/after visible-line count and the "what moved where" summary. ## Reference - Transformation playbook, `
` patterns, and the envprism before/after: [REFERENCE.md](REFERENCE.md). - House-style source of truth (emojis, badges, closers): [`write-readme`](../write-readme/SKILL.md) and its [REFERENCE.md](../write-readme/REFERENCE.md).