rabbit-readme-improver
README writing
Write or edit README.md using conventions measured from real data, not folklore. The full study (methodology, the 100-repo table, every stat cited below) lives in ${CLAUDE_PLUGIN_ROOT}/docs/README_WRITEUP.md. This file is the operational summary. Read references/patterns.md for the fuller catalog with more examples, and references/checklist.md at the end of any draft or edit.
Paths. ${CLAUDE_PLUGIN_ROOT}/skills/ means the directory holding this skill and its siblings (rabbit-writes, voice-setup, rabbit-readme-improver, rabbit-reads, rabbit-rewrites, rabbit-claude-md). Claude Code expands the variable. On a host that doesn't, such as Codex, resolve it that way by hand. ${CLAUDE_PLUGIN_ROOT}/docs/ only exists in a full-repo install. When it's missing, references/patterns.md carries the same numbers and scripts/readme_check.py still runs, since it resolves its siblings from its own location.
Modes
| Mode | Trigger | Deliver |
|---|---|---|
| draft | New project, no README yet, or "write me a README" | A complete README.md built in the measured section order |
| audit | "review my README", "does this follow best practices" | Findings against the checklist, ordered by impact, no rewrite unless asked |
| restructure | Content exists but is disorganized, or reordering is the ask | Same content, reordered into the measured convention, noting what moved |
| section | "add a badges row", "write the install section" | Just that section, matching the surrounding document's register |
Default to draft when there's no README and the user describes a project. Default to audit when a README exists and the ask is open-ended ("can you look at my README").