write-clear-readme

name	write-clear-readme
description	Author, audit, or polish a project README — clarity, structure (Pattern A grouped collapse / Pattern B per-entry collapse), wording concision, anchor integrity. Reads the repo first, proposes diffs, applies on approval.
when_to_use	When the user wants to create, restructure, audit, or polish a README for clarity, conciseness, or scannable structure. Keywords — write readme, author readme, audit readme, polish readme, clarify readme, optimize readme, restructure readme, README clarity, README wording, scannable readme. Useful for skill libraries, plugin monorepos, npm SDK references, CLI manuals, or any README showing scroll fatigue, unclear writing, or verbose passages. Skip when the user wants only spelling/grammar corrections — use `/fix-grammar` instead.
argument-hint	[author|audit|polish] [optional path — defaults to ./README.md]
model	opus
disable-model-invocation	true
allowed-tools	Read Write Edit Grep Glob Bash(git *) Bash(jq *)
license	MIT
compatibility	Claude Code CLI (per Agent Skills spec). Graceful degradation in other environments supporting the open standard.
metadata	{"author":"coroboros"}

Write Clear README

Author, audit, or polish a README.md for clarity, conciseness, and scannable structure. Reads the repo state first; uses <details> collapse patterns where appropriate; proposes diffs and applies on approval.

Additional context from the user: $ARGUMENTS

Context

• Repo: !basename $(git rev-parse --show-toplevel 2>/dev/null || echo unknown)
• Existing README: !test -f README.md && wc -l < README.md | awk '{print $1 " lines"}' || echo "none"
• Package manifest: !test -f package.json && jq -r '.name + "@" + .version' package.json 2>/dev/null || echo "none"
• Top-level folders: !ls -d */ 2>/dev/null | head -20 | tr '\n' ' '

Two patterns

Long READMEs cause scroll fatigue — readers skim past important sections, lose their place, or give up. Collapse structural details with HTML <details> blocks. GitHub and most markdown renderers support them natively.

Pattern A — Grouped collapse

When: a doc lists 5+ peer items that cluster into a small number of logical groups (≤7). Typical: skill libraries, plugin ecosystems, monorepo package indexes, component catalogs.

Group heading OUTSIDE <details> so #group-name anchors keep working, per-item headings inside:

### Group Name

<details>
<summary><em>Expand — item1 · item2 · item3</em></summary>

<br>

#### item1
...

#### item2
...

</details>

Keep an overview table at the top listing all items with anchor links — users see the full scope without clicking.

Pattern B — Per-entry collapse

When: reference docs with dozens of API entries, functions, CLI commands, or config options. Typical: npm package READMEs, SDK references, CLI manuals.