/re0-readme

name: re0-readme
description: "Keep a repository's README for the person deciding whether and how to use it, its AGENTS.md (or a CLAUDE.md read through it) for the agent working inside it, and the manifests hosts read first (package.json, plugin and marketplace files, agents/openai.yaml) on the repository's one name: audit them with the bundled script, then move each line to the file whose reader needs it and fix each disagreeing manifest. Use when writing, rewriting or reviewing a README or an AGENTS.md, when an agent-only command shows up in a README or marketing copy in an agent guide, when deciding which file a section belongs in, or after a rename. Not for contracts, ledgers, changelogs or release notes."

Audit a repository's README, AGENTS.md and manifests with the bundled script, then move, rewrite or keep each flagged line so it lives in the file whose reader needs it, and correct each manifest that disagrees with the repository.

Goal

README.md serves a person deciding whether and how to use the repository. AGENTS.md serves an agent working inside it: layout, commands, gates, conventions. Each line lives in the file whose reader needs it. A fact both readers need takes one form per reader (the address a person opens in README, the configuration an agent maintains in AGENTS.md); neither file restates the other's procedure, and each links rather than copies. The manifests a host or registry shows before either file is opened (package.json, `.claude-plugin/` and `.codex-plugin/` plugin files, marketplace files, each skill's `agents/openai.yaml`) answer to the repository's one name, point at its own address, and list exactly the skill folders it ships, so a rename that reaches README but not a manifest leaves the old name on every host that lists it.

The trigger is a README or AGENTS.md that is about to be written, was just written, or is under review, or a line in one suspected of serving the other file's reader. The input is the repository root (the repository the request is about, or the working directory's when none is named), and optionally the kind, extra local-state folder names, and whether the run may rewrite or must only report.

Every run reports the baseline audit, its kind and source, each finding's rule id, file, line and severity, and a keep list with reasons. A review-only run reports proposed moves and stops without edits, an after audit or a hosted audit. An already-green run reports the baseline and stops unchanged. A rewrite reports the edited files, the after audit and the hosted audit or its unresolved failure.

When the baseline audit is green, review every finding and the intended changes, including manifest corrections; stop unchanged only if none needs action. Zero edits is a successful run.

Workflow

1. **Run the audit before any edit** and keep its output as the baseline. From this skill's folder:

   node scripts/audit.mjs [<repo-root>] [--kind app|cli|library|skills] [--loop-dir <name>]... [--host <owner/repo>] [--strict] [--json] [--rules]

It reports each finding with its rule id, file, line and severity, sorted by file, line, then rule id. `--json` prints the result as one JSON object; `--rules` prints every rule id with its severity per kind. Exit codes: 0 no fail finding; 1 a fail finding, any finding under --strict, or AGENTS.md missing; 2 a usage error or an unreadable input (unknown kind, a root that is not a directory, a package.json that does not parse). An exit of 2 is a broken run, never a red audit: fix the command or the input and run again. When only CLAUDE.md exists, read it as the agent guide and report the missing AGENTS.md failure; a rewrite may create AGENTS.md as the guide or a link to CLAUDE.md, then rerun the audit. A review proposes that repair without writing. 2. **Check the kind.** The kind is detected from repository files unless `--kind` is given; compare it with what the repository ships and pass `--kind` when detection is wrong. A dot folder the repository's own .gitignore excludes is treated as local state, and `--loop-dir` adds one more name per use, so pass it for a local-state folder the .gitignore does not name. The kind decides severity: commands are product surface for a CLI, agent vocabulary is the subject of a skills catalog, pictures are product for an app. 3. **Read every finding in context.** A match is a lead, never a verdict: a troubleshooting variable can belong in a README, and a contributor test command can stay as a note. Decide move, rewrite, or keep for each finding, and write the reason for each keep into the keep list, which goes in the report rather than a file. When a fact is copied into both files, or into a third doc, beyond the one-form-per-reader split, call the Skill tool with "ssotize" (`paperthin:ssotize`). 4. **Stop here on a review request.** A request to review, audit or check reports the baseline, the proposed move for each finding and the keep list, and edits nothing. Continue only when the request is to write, fix or rewrite the files. 5. **Rewrite README for its reader**, in the language that reader reads, which the repository's owner or its sibling repositories set, never the language the code happens to be written in: lead with one sentence saying what the product is, then what it does today as measured, then a visible result or usage example, the shortest working setup, supported environments, dependencies that matter, and links to deeper docs. A product that does less than it was built to do says so near the top, with the measurement, and says what it was designed for only as the goal; a README describing the design as the present misleads the reader the file exists for. In list tables, turn grouping columns into sections, show status with an icon and a word, and give the legend once. Keep operational detail only where it helps a person use or contribute. When stack, vendor or tool nouns in README stand for a mechanism, call the Skill tool with "de