Multi-agent review of user-facing docs (README, docs/**, --help text) for simplicity and correctness. Use before any release, after any feature PR that touched docs, or when asked to review docs.
Installs into .claude/skills of the current project.
Are you the author of Review Docs?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/anandgupta42-review-docs)
---
name: review-docs
description: "Multi-agent review of user-facing docs (README, docs/**, --help text) for simplicity and correctness. Use before any release, after any feature PR that touched docs, or when asked to review docs."
trigger: /review-docs
---
# /review-docs — the docs panel (group review, two lenses)
Docs are product surface. This skill runs **at least two independent agent reviewers in
separate contexts** — never one agent wearing both hats, never the agent that wrote the
docs — then consolidates findings and applies fixes.
## Reviewer A — the cold reader (simplicity)
Prompt an agent that has NEVER seen this repo: it gets README.md (and only what the
README links) and must, in order: (1) say in one sentence what the tool does; (2) run
the quickstart commands verbatim against a fixture; (3) flag every place it stumbled —
jargon, missing steps, buried assumptions, anything it had to guess. Length findings
count: a section a cold reader skips is a section to cut. Deliverable: stumble list +
the one-sentence comprehension check.
## Reviewer B — the correctness auditor
A separate agent (different context; Codex preferred — different model family) audits
every claim against the code:
- Every command/flag in README, docs/**, and `--help` exists and runs with exit 0 on a
fixture (execute them — don't eyeball).
- Every factual claim maps to code (`file:line`) or a test; overclaims are findings
(I3: docs never promise more than the code does — "never/always/zero" claims get
special scrutiny).
- Parity surfaces verified: docs/telemetry.md ↔ zod schemas (the SPEC-0002 test),
docs/json-schema.md ↔ schema when it exists, help text ↔ args.ts.
- Stale references: renamed flags, removed commands, dead links, version drift.
## Consolidate, fix, record
Merge both lists, dedupe, apply the accepted fixes (docs edits are cheap — default to
fixing, not filing), note rejected findings with one-line reasons. Record the panel's
verdict (reviewers, findings count, fixes applied) in the PR or release notes. Docs
review is BLOCKING for a release; advisory-but-expected for feature PRs.
