# Write Clear Readme

> 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.

- Skill: `aibot88/write-clear-readme` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/write-clear-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/write-clear-readme/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aibot88/write-clear-readme

---


<!--
Exception — `disable-model-invocation: true`. READMEs are high-stakes, user-facing
artifacts; Claude should never autonomously decide to rewrite one based on a casual
keyword. The user must explicitly invoke via `/write-clear-readme`. The `when_to_use`
keywords still help the user discover the skill in the `/` menu listing (per
`claude-code-skills.md`, skill listing is independent from model auto-invocation).
-->

# 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:

```markdown
### 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.

Signature in `<summary>` (inside `<code>` for monospace), one-line description after an em-dash, full detail hidden until expanded:

````markdown
## API

<details>
<summary><code>functionName(arg: T, opts?: Options): Result</code> — one-line description</summary>

<br>

Longer explanation. Params table, return value, edge cases, examples.

```ts
// usage
```

</details>

<details>
<summary><code>anotherFunction(x: X): Y</code> — what it does</summary>
...
</details>
````

Underused pattern — most npm READMEs list signatures as flat headings and force a 3000-line scroll. The `<details>` version is dramatically more scannable for reference-heavy docs.

## Universal rules

- **Overview visible** — TOC, tables, API index stay uncollapsed. Collapse *details*, not the *list*.
- **Anchors preserved** — navigation targets (group headings, API section heading) go OUTSIDE `<details>`. Headings inside still auto-anchor, and GitHub auto-expands the parent `<details>` on hash navigation.
- **`<br>` after `<summary>`** — markdown rendering inside `<details>` can be flaky; the explicit break is defensive and consistent.
- **No deep nesting** — one level of `<details>` max; nested collapsibles confuse navigation.
- **Signature-first summary (Pattern B)** — put the most identifying token first (function signature, command name, option name) so `Ctrl+F` hits the right entry immediately.

## When NOT to use

- Short docs (< 5 major sections) — adds clicks for no scroll savings
- Install / Quick Start / Requirements — users need these instantly visible
- Single-purpose tools where the README is already concise

## Subcommands

| Invocation | Mode |
|------------|------|
| `/write-clear-readme` | Default — if `README.md` exists, audit. Else, author from repo state. |
| `/write-clear-readme author [path]` | Create or fully restructure a README from scratch. |
| `/write-clear-readme audit [path]` | Review existing README for collapse opportunities + anchor/overview integrity + clarity issues. |
| `/write-clear-readme polish [path]` | Tighten wording, drop filler, clarify ambiguous passages — preserve structure, change only the prose. |

## Clarity rules

Whether authoring, auditing, or polishing — the prose itself follows these:

- **One idea per sentence.** Compound sentences with multiple clauses get split.
- **Front-load the verb.** "This skill helps you create" → "Create [...] with this skill" or simply "Creates [...]".
- **Drop filler.** "In order to" → "to". "It's important to note that" → delete. "Please make sure to" → imperative.
- **Concrete over abstract.** "Various improvements" → list 2-3 specific ones. "Optimized" → say *what* was optimized.
- **No marketing voice.** No "powerful", "robust", "delightful", "seamlessly", "leverage", "unlock". Replace with the actual capability or remove.
- **Show the shape early.** First 3 lines should let a reader decide if this README is for them — what the project is, who it's for, what it does (one verb).
- **Backtick code-like tokens** — file paths, command names, function names, env vars. `~/.claude/rules/` not ~/.claude/rules/.
- **Em-dashes for context, not parentheses** — `(also see foo)` → `— also see foo`. Reads less aside-y.
- **Lists over paragraphs** when the content is enumerable (≥3 items of the same kind).
- **Headings as questions or commands**, not topics. "Installation" is fine; "How do I install?" or "Install" reads quicker than "About installation".

## Adjacent skills

- **`/fix-grammar`** — optional typo / spelling pre-pass before authoring, or post-pass after polish when the source has obvious errors. Skip when the text is already clean — this skill never introduces grammar errors.
- **`/humanize-en`** — AI-tell stripping (see next section). Called by `author` and `polish` modes after clarity edits; `audit` mode flags AI tells without rewriting. Also usable standalone.

## Remove AI traces

After any author or polish pass on English content, strip residual AI tells (em-dash overuse, rule of three, negative parallelisms, AI vocabulary, vague attributions, promotional tone, conjunctive padding like "moreover", "furthermore", "indeed").

- **Invoke `/humanize-en` if installed** — detects and fixes all 32 patterns in a single pass. Run it after clarity edits land but before presenting the diff. The skill preserves structure, code blocks, links, anchors, and frontmatter.
- **If the skill is not available**, scan manually for those patterns (see `humanize-en` or [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) for the full list) before shipping. Do not block on a missing skill.
- **Audit mode:** flag suspected AI tells in the findings but do not auto-rewrite.
- **Non-English content** — skip this step entirely; `humanize-en` is English-only.

## Author mode

1. **Inspect repo** — read `package.json` / `Cargo.toml`, top-level folders, entry points, `CLAUDE.md` if present. Identify what the README must cover (install, usage, API surface, architecture, license).
2. **Pick a pattern** —
   - Pattern A if 5+ peer items cluster into ≤7 groups (skill library, plugin list, monorepo packages)
   - Pattern B if the doc is reference-heavy (dozens of API entries, CLI commands, config options)
   - Short doc (< 5 sections) → no collapse
3. **Draft** — overview table at top with anchor links, Install / Quick Start / Requirements uncollapsed, grouped or per-entry collapse below. Apply Clarity rules as you write.
4. **Remove AI traces** — for English content, invoke `/humanize-en` on the draft (see *Remove AI traces* above). Skip if the skill is unavailable or the content is non-English.
5. **Verify** — every TOC anchor resolves. Every `<details>` has a `<br>` after `<summary>`. No nested collapsibles. Install block is never inside `<details>`.
6. **Write** — overwrite or create `README.md`. Present the diff if it existed before.

## Audit mode

1. **Read existing README** in full.
2. **Run the structural audit script**: `${CLAUDE_SKILL_DIR}/scripts/audit_readme.py <path>` emits a JSON report covering unresolved anchors, nested `<details>`, missing `<br>` after `<summary>`, and a bloat-token scan (see the script's docstring for the canonical token list). Exit 1 on findings; the JSON is your hit-list. Subjective prose issues (First-3-lines test, verbose passages, marketing voice in context) still need your read.
3. **Score against Universal rules** (structure — use the script output first):
   - Is the overview (TOC / index / table) visible without clicking?
   - Do all anchors resolve? (Every heading referenced in the TOC must exist and be outside `<details>`.)
   - Are any `<details>` blocks nested?
   - Is `<br>` present after every `<summary>`?
4. **Score against Clarity rules** (prose — the script covers mechanical bloat, you cover the rest):
   - First 3 lines tell the reader what/who/why?
   - Verbose passages where bullets would do?
   - Code-like tokens unbacktick'd?
5. **Detect anti-patterns**:
   - Flat signature list 50+ lines deep → recommend Pattern B
   - 10+ peer sections without grouping → recommend Pattern A
   - `<details>` wrapping a group/section heading → broken anchor, must move heading outside
   - Nested `<details>` → flatten to one level (flagged by the script)
   - Install / Quick Start / Requirements inside a `<details>` → must surface
6. **Report** — bullet list of findings (split structure vs clarity) + proposed diff.
7. **Apply on request** — edit `README.md` only after explicit user approval.

## Polish mode

Wording-only pass. Structure stays as-is — only the prose changes.

1. **Read existing README** in full.
2. **Apply Clarity rules** sentence by sentence:
   - Drop filler phrases
   - Replace marketing voice with concrete verbs
   - Split compound sentences
   - Tighten verbose passages into bullets when enumerable
   - Backtick code-like tokens
   - Replace `(parens)` with em-dashes where they're aside-context
3. **Remove AI traces** — for English content, invoke `/humanize-en` on the result (see *Remove AI traces* above). Skip if the skill is unavailable or the content is non-English.
4. **Preserve** all anchors, headings, code blocks, diagrams, badges, and link URLs verbatim.
5. **Report** — propose a diff. NEVER apply without explicit approval.

## Rules

- NEVER auto-apply changes without user approval
- NEVER collapse Install / Quick Start / Requirements
- NEVER nest `<details>` blocks
- NEVER wrap a group heading or a TOC anchor target inside `<details>`
- NEVER change anchors, code blocks, or link URLs in polish mode (those are content, not prose)
- ALWAYS add `<br>` after `<summary>`
- ALWAYS match the existing README's style (quote convention, heading hierarchy, badge format) when editing
- Ignore `$ARGUMENTS` only if empty — otherwise treat first token as subcommand and second as path