From nexus-agents
Scores technical docs (RFCs, ADRs, READMEs, CLAUDE.md, blog posts) against a 5-category 100-point rubric. Read-only audit that surfaces top issues by severity and defers prose-quality analysis to existing user-level skills.
How this skill is triggered — by the user, by Claude, or both
Slash command
/nexus-agents:docs-reviewThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!--
Use when scoring an existing technical doc — RFC, ADR, README,
CLAUDE.md, architecture doc, blog-style technical post. Read-only;
produces a punch list, not a rewrite. The active counterpart is
docs-rewrite which runs review → research → rewrite → validate.
Trigger keywords: review docs · audit docs · score this doc · doc quality · docs review · doc audit.
Mechanical extraction (no judgment yet):
(source, year) form)[ORIGINAL DATA] / [PERSONAL EXPERIENCE] /
[UNIQUE INSIGHT])./other-doc.md and #anchor referencesCite the file paths + line numbers wherever you observe a problem.
The rubric defers the prose-quality lenses to existing user-level skills. Run them and quote their findings into the score, don't re-derive them inline:
| Rubric category | Defer to | Quote |
|---|---|---|
| Argument Strength § thesis + falsifiability | blog-argument-shape | "Thesis: . Falsifiability: ." |
| Source / Evidence § citations verified | blog-factcheck | The skill's punch list, as-is. |
| Content Quality § AI-tell scan | blog-llm-tells | The skill's findings, as-is. |
| Structure § cross-doc consistency | blog-overlap (when applicable) | STRONG / MODERATE / WEAK |
If blog-pre-publish is available, run it as a single invocation —
that's the orchestrator that bundles the four. Quote its consolidated
punch list.
These have no analog in the user-level skills; this is where
docs-review adds value:
Argument Strength (20 pts) — partial: "Locatable thesis" [M] +
"Close revisits the thesis" [J] + "One claim per doc" [J] are
scored here even though the deeper lenses defer. (4 + 3 + 2 = 9 pts of
the 20 from the skill alone; the remaining 11 come from
blog-argument-shape.)
Source / Evidence (25 pts) — partial: "Inline citations on every
claim" [M], "Year + URL + retrieval date" [M], "Code/spec links
resolve" [M], "First-hand evidence flagged" [M] are mechanical
checks (12 pts). The remaining 13 come from blog-factcheck + tier
verification (manual judgment).
Content Quality (25 pts) — partial: "Answer-first H2s" [M],
"Sentence discipline" [M], "Paragraph discipline" [M], "H2
cadence" [M], "Glossary / first-use definitions" [M] (18 pts) are
mechanical. AI-tell scan defers to blog-llm-tells (4 pts). "No
unsupported assertion" is judgment (3 pts).
Structure (20 pts) — fully scored here: heading hierarchy, code
blocks valid, internal links resolve, summary box / TL;DR,
frontmatter on tier-1/2 docs (per CLAUDE.md FRONTMATTER_REQUIRED_FILES
gate), spec/RFC alignment, file-size + sprawl. Cross-doc consistency
defers to blog-overlap.
Audience Fit (10 pts) — fully scored here: persona-appropriate readability band (advisory), reader's prior knowledge stated, length matches purpose, examples for the audience.
Don't dump every observation. Bin into Critical / High / Medium / Low and surface only the top 10. Reviewers won't act on a 47-item punch list.
For each issue, output:
# Docs Review: <filename>
**Score: 78 / 100** (prior baseline: 71 / 100; +7)
| Category | Score | Top issues |
| ----------------- | ------- | ---------- |
| Argument Strength | 16 / 20 | thesis is hedged (first paragraph has 3 questions) |
| Source / Evidence | 19 / 25 | 2 unverified citations (per blog-factcheck) |
| Content Quality | 21 / 25 | passive voice 14% (target ≤ 10%) |
| Structure | 15 / 20 | code-block in §3.2 missing language tag |
| Audience Fit | 7 / 10 | Flesch 22 (band 30-50 for technical docs) — too dense |
## Top 10 issues
1. [Critical] file.md:42 — Argument: thesis is buried under 3 hedging questions.
Recommend: hoist a single declarative claim to the first paragraph.
2. [High] file.md:128 — Source: "studies show 80% improvement" has no citation.
Recommend: add (source, year) or remove the claim.
... (8 more)
docs-rewrite..rules/docs-rubric.md — the canonical rubric this skill appliesskills/docs-rewrite — the active rewrite counterpart (uses the
same rubric for audit + validate)skills/documentation-management — operating manual for doc workblog-pre-publish — orchestrator for the prose-quality
lensesnpx claudepluginhub nexus-substrate/nexus-agentsReviews documentation from a novice user's perspective, rating clarity, completeness, actionability, and structure. Outputs prioritized issues and concrete suggested fixes.
Reviews .md documents and tech specs using Codex MCP, producing a 5-dimension rating table with pass/fail gate. Supports review loops for iterative fixes.
Improves technical docs in-place via phased Audit → Research → Rewrite → Validate workflow. Calls docs-review for scoring; applies rubric-defined formatting rules.