| name | docs-review |
| description | Perform comprehensive editorial reviews of documentation with a tech writer / copyeditor lens. Use when asked to review docs, documentation changes, or a set of changed files - especially net-new documentation or LLM-generated content. Reviews can be for single documents or multiple related documents. Focuses on information architecture, clarity, conciseness, structure, readability, and style. Identifies common LLM writing patterns that harm documentation quality and catches multi-document issues like content duplication or misplaced content. For reviewing a pull request end-to-end (fetching the PR branch, checking review threads, drafting a review to post), use the review-docs-pr skill, which applies these criteria as one of its steps.
|
Documentation Review
Perform critical editorial reviews as a tech writer / copyeditor, focusing on clarity, conciseness, structure, and readability.
Review Process
- Read the document(s) fully before making observations
- Check related documents if reviewing changes to existing docs or new docs in a doc set
- Check the project style guide.
STYLE-GUIDE.md is authoritative for terminology, naming, and page structure. AGENTS.md (symlinked as CLAUDE.md) restates a subset for agents; where the two differ, the style guide wins
- Verify claims against authoritative sources - cross-check documented behavior against CLI reference docs, API specs, auto-generated references, and upstream specifications. Note: docs may be drafted ahead of a release, so auto-generated references may lag behind - flag contradictions, not just absences
- Walk through as the reader - mentally follow the page as a user doing the task for the first time. Are prerequisites complete? Can you follow each step in order? Would you have the knowledge needed at each point, or does the page assume something it hasn't established?
- Assess information architecture - document placement, scope, cross-document duplication
- Assess overall structure - TOC length, information flow, Diataxis alignment
- Identify specific issues with concrete examples and line numbers
- Provide actionable recommendations - not just problems, but solutions
Primary Review Criteria
Information Architecture
Document placement and scope - Check first, as misplaced content is more critical than prose issues:
- Right document test: Does content match the document's core purpose?
- Configuration content doesn't belong in mode-selection guides
- Operational monitoring isn't discovery-mode-specific
- Example: "Health checks apply to both modes" → belongs in general config, not mode guide
- Single source of truth: Same topic documented in multiple places?
- Keep detailed content in ONE location
- Others link to it with brief context
- Red flag: Same config section in 3+ documents
- Document scope drift: Content that doesn't match the title/purpose
- If removing a section wouldn't hurt the doc's main goal, it probably doesn't belong
- Missing cross-references: Related topics should link bidirectionally
Diataxis document type alignment:
- How-to guides: Should focus on ONE task/problem, not multiple unrelated tasks
- Tutorials: Don't mix with reference material or troubleshooting
- Reference: Keep conceptual explanations and "why" separate
- Concepts: Should explain trade-offs and "when to use" clearly
Structure and Length
- TOC test: If the table of contents fills a screen, the doc is likely too long
- Heading count: 20+ headings signals over-segmentation; consolidate
- Information flow: Conceptual content (trade-offs, when to use) should come before implementation details, not after
- Admonition weight: Tips, notes, and warnings should be supplementary. If an admonition contains primary feature documentation (full YAML examples, the only explanation of a field or concept), it should be promoted to a proper section or its own page. A good test: if this admonition is the only place a feature is documented, it's not a tip - it's a section that needs a heading and ToC visibility.
- Enterprise construct usage: Three constructs exist for enterprise content - check they're used correctly.
:::enterprise admonitions are for callout blocks (2-4 sentences, max 1-2 per page). <EnterpriseBadge /> is for inline feature labels next to headings or list items. className: 'enterprise-only' in the sidebar is for enterprise-only pages. Flag misuse: enterprise admonitions used for single-feature labels (use <EnterpriseBadge /> instead), badge used on entire page descriptions (use the admonition instead), or excessive enterprise admonitions on a single page.
- Diataxis alignment: Don't mix tutorials, how-tos, reference, and concepts in one doc without clear separation
LLM-Generated Content Patterns
Watch for these telltale signs of AI-generated docs that need human intervention. The tech-writer skill maintains the write-time version of this catalog (.claude/skills/tech-writer/references/anti-patterns.md); when you add a pattern here, add it there too.
| Pattern | Problem | Fix |
|---|
| Flat option coverage | Every option/flag gets equal billing; the common workflow drowns in the long tail | Weight coverage by real-world use: worked example for the common path, a sentence + reference link for situational options, reference only for esoteric knobs |
| Excessive lists | Hard to scan, staccato reading | Convert to prose or tables |
| Mirror-image sections | "When to use X" / "When to use Y" as inverted duplicates | Consolidate into comparison table |
| Buried ledes | Key info (e.g., "it's automatic") comes after lengthy preamble | Lead with the most important point |
| Repetitive content | Same info in multiple sections | Deduplicate; single source of truth |
| Over-explaining | Verbose descriptions of obvious things | Trust the reader; cut aggressively |
| Hedging language | "may," "might," "could potentially" | Be direct or remove |
| Em/en dashes | — or – used as inline separators | Rephrase naturally: use commas, split sentences, or restructure. Use spaced hyphens (-) only in list-style contexts |
| Hedged lists | "such as," "including," "clients include" when listing supported items | Be definitive: state the full list, or link to a canonical reference |
| Placeholder examples | my-skill, example-org, my-app where a real product value exists | Use real values for fixed things (commands, flags, image names); use <ALL_CAPS> placeholders for values the reader supplies; use reserved domains (example.com) in URLs, never real domains |
| Features without context | Introduces a flag/option without explaining why a reader would use it | Explain the user benefit and how it connects to concepts the reader already knows |
| Changelog framing | "Starting in vX.Y," "previously," "moved from X to Y" - narrating the transition instead of the current behavior | State current behavior only; transitions belong in release notes. Common in release-driven PRs where the diff (the delta) leaks into the prose. Exception: a clearly labeled, versioned admonition for a breaking or silently-behavioral change that upgraders must act on is valid (see the style guide); flag those only when stale (several releases old) or duplicating adjacent prose |
| Negative restatement | "X, not Y" or a "Don't do Z" sentence that inverts the positive statement just made | Cut it, or fold any genuinely new fact into the positive statement |
| Redundant admonitions | A note or warning that restates adjacent body text, often with added negation | Cut it; an admonition must add information beyond the surrounding prose |
| PR jargon leak | Engineering shorthand from PR descriptions ("consumers," "shapes," "surface area," "wire up") | Name the concrete components, fields, and values |
Section Structure and Navigation
The docs follow a product-area-based information architecture under docs/toolhive/. Check:
- Self-contained sections: Product-specific content belongs in its product section (
docs/toolhive/guides-ui/, guides-cli/, guides-k8s/, guides-vmcp/, guides-registry/), not in a shared section.
- Quickstarts in product sections: Quickstarts live inside their product section, not in a separate top-level section.
- Integration placement: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in
integrations/, not in a product section.
- Page ending pattern: How-to guides and tutorials follow this closing pattern: Next steps > Related information > Troubleshooting (if applicable). "Next steps" contains 1-3 forward links to the next logical pages. Missing "Next steps" is a primary issue.
- Inbound link coverage for new pages: When a PR adds a new page, check that it is reachable beyond just the sidebar. New pages need inbound links from related pages (overviews, intros, feature lists, related how-to guides). A page with no inbound links is isolated in the user journey. For major new features, also check whether top-level intro/overview pages should mention the capability.
- Introduction pages: Each product section should have an Introduction as the first sidebar child. New sections must follow this pattern.
- Progressive disclosure: Core workflows should appear before advanced topics. Check that advanced content isn't mixed in with beginner-facing pages.
- Pattern consistency for peer concepts: When a PR introduces a new resource type, feature, or component that has established peers in the doc set, check whether it follows the same documentation pattern (dedicated page, equivalent depth of coverage, parallel sidebar placement). A new CRD documented only as a subsection of another page, when its peer CRDs each have their own page, is a structural gap. When a PR adds a guide that references a CRD (e.g. links to
/toolhive/reference/crds/<kind>), verify the target page exists. A broken cross-reference is usually the symptom of a missing scripts/lib/crd-intros.mjs entry that was never followed up on from a prior release PR.
- Forward navigation path: A reader should be able to follow "Next steps" links from the quickstart through core workflows without relying on the sidebar.
Clarity and Readability
- Passive voice: "Backend discovery occurs" → "vMCP discovers backends"
- Redundant phrasing: "uses discovered mode to automatically discover" → "automatically discovers"
- Unexplained design decisions: If something seems non-obvious (e.g., why a field is named counterintuitively), the doc should explain it
- Inconsistent terminology: Pick one term and use it consistently throughout
- Ambiguous product terms: When a product has components with overlapping names (e.g., "Registry" could mean a built-in registry or a Registry Server instance), docs must disambiguate. Readers at different points in their journey have different mental models
- Prerequisites lacking operational context: Don't just say "X must be running" - explain practical implications (is it a blocking command that needs a separate terminal? does it need to stay running persistently, or only during specific operations?)
- Missing cross-references: Related docs should link to each other. When a how-to page lists supported items (clients, platforms, etc.), link to the canonical reference rather than maintaining an inline list that can drift
Accuracy and Trustworthiness
Docs that readers can't trust are worse than no docs. Actively verify:
- Cross-check against reference material: Does the prose contradict the auto-generated CLI reference, the API spec, or the upstream project's docs? Flag contradictions. Note: docs are often drafted before a release, so auto-generated references may not yet include new features - absence from the reference is not the same as a contradiction. But if an existing reference explicitly describes different behavior (e.g., "by name or OCI reference" when the prose also claims Git support), that's a real conflict to flag
- Code examples must work: Could a reader copy-paste this and get the described result? Check for correct syntax, realistic flag combinations, and valid argument values. Generic placeholders (
my-skill, foo) should be replaced with real product values where the value is fixed, or <ALL_CAPS> placeholders where the reader supplies it. Domains in example URLs are the exception: use reserved domains (example.com), not real ones
- Feature coverage completeness: When documenting a new feature, check that the full surface area is covered. Are all subcommands/endpoints mentioned? Are common error states addressed? A how-to that covers the happy path but ignores the most likely failure mode will generate support questions
- Consistency across the doc set: Do the same terms, flag names, and behaviors described here match how they're described in related pages? Cross-document inconsistencies (e.g., one page says "space-delimited," another uses comma-separated) erode trust
Front Matter Descriptions
The description field serves double duty: DocCard preview (truncated at ~70-75 characters) and <meta> description for SEO (ideally 80-150 characters total). Check for:
- Front-loading: The first 70 characters must be a useful standalone summary. If the DocCard cutoff would leave a confusing fragment, the description needs rewriting
- Filler openers: Flag descriptions starting with "Learn how to," "Understanding," "A guide to," "This page describes," or similar. Lead with the action or topic
- Too short (under 50 characters): Misses SEO value. Expand with concrete detail about what the page covers
- Too long (over 160 characters): Will be truncated in search results. Tighten
- YAML safety: Unquoted colons (
:) inside description values break YAML parsing. Flag and suggest rephrasing or quoting
Accessibility and Formatting
- Emojis in prose: Can cause screen reader issues; use sparingly or not at all
- Long code blocks without context: Add titles and highlight key lines, stay focused on the concept being explained
- Tables vs lists: Tables are better for comparisons; lists for sequences
- Collapsible sections: Use for lengthy troubleshooting or optional details
Output Format
Structure your review as:
## Summary
[1-2 sentence overall assessment]
## Primary Issues
### 1. [Issue name]
[Description with specific line numbers] **Ask:** [Concrete action to take]
### 2. [Issue name]
...
## Secondary Issues
| Issue | Recommendation |
| ----- | -------------- |
| ... | ... |
Severity Guidelines
Before including any finding, apply the independent reviewer test: would a different competent tech writer independently flag the same issue? If two phrasings are equally clear and correct, don't flag one as better. The goal is a stable review - running the skill twice on the same document should produce essentially the same findings.
Primary issues (address before merge):
- Accuracy: documented behavior contradicts CLI reference, API spec, or upstream source
- Accuracy: code examples that won't work if copy-pasted (wrong syntax, nonexistent flags, invalid arguments)
- Information architecture: content in wrong document, cross-document duplication
- Content placed in the wrong section (e.g., product-specific content in Concepts, integration content in a product section)
- Missing "Next steps" section on how-to guides and tutorials
- Structure problems that harm navigation
- Missing explanations for confusing design decisions
- Significantly buried or redundant content
- Grammatical errors (sentence fragments, missing articles, subject-verb disagreement)
Secondary issues (worth fixing but not blocking):
- Wording that is genuinely confusing, ambiguous, or likely to mislead - not merely "could be rephrased"
- Style guide violations (terminology, capitalization, voice)
- Missing context that forces the reader to leave the page to understand a step
Skip entirely:
- Formatting/syntax (let linters handle this)
- Style-neutral alternatives where the current version is clear (e.g., "this sentence could be split in two," "this transition could be cut," imperative vs. declarative phrasing)
- Thin but useful sections - a short section that orients the reader is better than no section; don't flag brevity alone
- Cosmetic rewording that doesn't change clarity or correctness
Review Checklist
Before finalizing your review, verify:
