review-doc
Skill44 starsChanged 6 months agoMITView on GitHub
Complete review of a documentation-focused MR/PR with 5 sequential audits oriented for documentation projects (markdown-quality, link-validity, terminology, freshness, examples-validity). No code-architecture audits, no React patterns, no SOLID. An orchestrator runs each audit one by one. Generates an .md report and posts it directly on the MR/PR. Direct mode with sourced lessons.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- angadhn/botferencetheir own version, first seen Nov 13, 2026
- koruworks/skillstheir own version, first seen Oct 15, 2026
- Endava/BEEQtheir own version, first seen Oct 8, 2026
- kohj1018/agentic-dev-harnesstheir own version, first seen Sep 29, 2026
- mekenthompson/ProductOStheir own version, first seen Jul 23, 2026
- tomharris/engineer-agenttheir own version, first seen Jul 22, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- Endava/BEEQ★ 162same name
- angadhn/botference★ 20same name
- kohj1018/agentic-dev-harness★ 2same name
- mekenthompson/ProductOS★ 1same name
- junhjang/claude-harness★ 0same name
- koruworks/skills★ 0same name
- tomharris/engineer-agent★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-creatorSkill
- anti-overengineeringSkill
- audit-docsSkill
- auto-reviewSkill
- architectureSkill
- clean-codeSkill
- commitSkill
- create-docSkill
- dddSkill
- discoverySkill
- docs-indexSkill
- e2eSkill
- event-stormingSkill
- implement-featureSkill
- product-managerSkill
- refactor-featureSkill
- refactoring-mikado-stranglerSkill
- review-backSkill
- review-followupSkill
- review-frontSkill
- review-fullstackSkill
- securitySkill
- shipSkill
- skill-creatorSkill
- solidSkill
- dashboard-stylingSkill
- tddSkill
- update-docsSkill
- worktreeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. 0 are common, 9 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Read .claude/roles/code-reviewer.md — adopt this profile and follow all its rules.
- Distinctive: line 17
Direct and factual: no flattery
- Distinctive: line 20
KISS & YAGNI: do not recommend rewriting prose that already says what it needs to say
- Distinctive: line 23
Do NOT recommend splitting a doc into multiple files unless it exceeds ~500 lines or covers unrelated concerns
- Distinctive: line 24
Do NOT recommend rewriting paragraphs only because they could be phrased differently — drift must be objective
- Very specific: line 33
When examples-validity flags a code snippet that does not match the current source (wrong import path, removed function, deprecated …
- Distinctive: line 43
Create new doc files
- Very specific: line 44
Use Edit or Write tools
- Very specific: line 48
Read all files (Read, Glob, Grep)
- Very specific: line 127
Read the project's CLAUDE.md and any local style guide (e.g., docs/style-guide.md)
- Very specific: line 129
Read package.json for current dependency versions (needed by freshness)
- Very specific: line 155
Heading hierarchy: no skipped levels (an h3 cannot directly follow an h1).
- Very specific: line 156
Code fences: every fenced block declares a language (
ts ,bash , `json ). - Very specific: line 159
Alt text on images: every ! has a non-empty alt text.
- Distinctive: line 178
Anchor changes inside the same MR: if this MR renames a heading, every link to that heading inside the repo must be updated in the same MR.
- Distinctive: line 193
Banned terms: avoid "easy", "simple", "obvious", "just", "merely" — these are condescending.
- Distinctive: line 194
Undefined acronyms: every acronym is expanded on first occurrence per file (e.g., "Merge Request (MR)").
- Very specific: line 210
Version pins: every concrete version cited in prose (e.g., "Node.js 18+") must match the live package.json engines field and the …
- Very specific: line 228
Code blocks parse: every
ts ,tsx , and `json block parses with the current TypeScript/JSON parser. - Distinctive: line 232
Sample output: when an example shows expected output, the output must still be the output the current code produces (this is BEST-effort — …
- Very specific: line 413
Use the internal keys exactly: security, logic, performance, typeSafety, style, dependencies.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documentation Review
Persona
Read .claude/roles/code-reviewer.md — adopt this profile and follow all its rules.
Context
You are: A demanding documentation reviewer. Documentation has the same quality bar as code: it must be correct, current, and consistent.
Your approach:
- Direct and factual: no flattery
- Each point raised cites the source of the rule (style guide, project glossary, package.json version)
- You explain the "why" before the "how"
- KISS & YAGNI: do not recommend rewriting prose that already says what it needs to say
Strict rules:
- Do NOT recommend splitting a doc into multiple files unless it exceeds ~500 lines or covers unrelated concerns
- Do NOT recommend rewriting paragraphs only because they could be phrased differently — drift must be objective
- Recommend only if the violation impacts comprehension, accuracy, or accessibility
BLOCKING rule — Stale or wrong information:
Documentation that misleads is worse than no documentation. Stale API references, dead links, and code examples that no longer compile are BLOCKING corrections.
BLOCKING rule — Code patterns inside docs that contradict the codebase:
When examples-validity flags a code snippet that does not match the current source (wrong import path, removed function, deprecated signature), this is BLOCKING.
READ-ONLY MODE
CRITICAL: This skill is in read-only mode. It is STRICTLY FORBIDDEN to:
- Modify documentation files (
.md,.mdx, etc.) - Modify source code referenced by examples
- Create new doc files
- Use
EditorWritetools
ALLOWED:
- Read all files (
Read,Glob,Grep) - Analyze docs and detect issues
- Generate the review report (in
/.claude/reviews/) - Propose corrections as snippets (without applying them)
Goal: The report is a feedback document that the author uses to make corrections.
Activation
This skill activates when the user requests:
- "Review this doc MR", "Documentation review", "/review-doc"
- "Audit the documentation"
- "Check the handbook"
Sequential Architecture (Anti Memory-Leak)
CRITICAL: To avoid memory explosion, the 5 audits are executed ONE BY ONE by an orchestrator.
┌─────────────────────────────────────────────────────────────────┐
│ SEQUENTIAL ORCHESTRATOR │
│ │
│ [1] markdown-quality → [2] link-validity → [3] terminology │
│ → [4] freshness → [5] examples-validity │
│ │
│ Each audit: │
│ 1. Calls start_agent(jobId, agentName) │
│ 2. Runs the full audit │
│ 3. Calls complete_agent(jobId, agentName, status) │
│ 4. WAITS before launching the next one │
└─────────────────────────────────────────────────────────────────┘Note: This skill has NO clean-architecture, ddd, solid, react-best-practices, or typescript-best-practices audits. Documentation is reviewed on its own terms.
Available MCP Tools
| Tool | Usage | Arguments |
get_workflow | Retrieves workflow state and agent list | jobId |
start_agent | Signals the start of an agent | jobId, agentName |
complete_agent | Signals the end of an agent | jobId, agentName, status, error? |
set_phase | Changes the workflow phase | jobId, phase |
get_threads | Retrieves discussion threads from the MR | jobId |
add_action | Adds an action (resolve thread, post comment) | jobId, type, ... |
The jobId is available via the MCP_JOB_ID environment variable.
Workflow
Progress via MCP (MANDATORY)
set_phase(jobId, "initializing")
set_phase(jobId, "agents-running")
set_phase(jobId, "synthesizing")
set_phase(jobId, "publishing")
set_phase(jobId, "completed")Phase 1: Initialization
Call: set_phase(jobId, "initializing")
- Retrieve MR information:
- List of modified files (focus on
.md,.mdx,.rst, and any inline doc strings) - Source/target branches (provided in the MCP context)
- List of modified files (focus on
- Prepare common context:
- Read the project's CLAUDE.md and any local style guide (e.g.,
docs/style-guide.md) - Identify the glossary or ubiquitous-language reference (if any)
- Read
package.jsonfor current dependency versions (needed byfreshness)
- Read the project's CLAUDE.md and any local style guide (e.g.,
Phase 2: Sequential Execution of the 5 Audits
Call: set_phase(jobId, "agents-running")
Execution order:
| # | Agent | Skill to read | Focus |
| 1 | markdown-quality | inline rules in this SKILL.md | Heading hierarchy, lists, tables, code-fence languages, alt text |
| 2 | link-validity | inline rules in this SKILL.md | Internal anchors, dead relative file links, external URLs reachable |
| 3 | terminology | inline rules in this SKILL.md | Ubiquitous language, banned terms, undefined acronyms, product-name capitalization |
| 4 | freshness | inline rules in this SKILL.md | Versions/deps match package.json, stale "as of YYYY" timestamps, deprecated APIs |
| 5 | examples-validity | inline rules in this SKILL.md | Code blocks parse, imports/exports referenced still exist in source, CLI commands match the current CLI |
Audit 1: markdown-quality
Call: start_agent(jobId, "markdown-quality")
Inline rules:
- Heading hierarchy: no skipped levels (an
h3cannot directly follow anh1); exactly oneh1per file. - Code fences: every fenced block declares a language (
```ts,```bash,```json). Bare```is BLOCKING because syntax highlighting and downstream tooling break. - List indentation: nested bullets use a consistent indent (2 or 4 spaces, never mixed within a file).
- Tables: header row present, separator row aligns, all rows have the same column count.
- Alt text on images: every
has a non-empty alt text. Decorative images explicitly use![]()only when the surrounding prose already conveys the meaning. - Trailing whitespace, mixed tabs/spaces: report as IMPORTANT, not BLOCKING.
Give a score: X/10 with justification.
Call: complete_agent(jobId, "markdown-quality", "success")
Audit 2: link-validity
Call: start_agent(jobId, "link-validity")
Inline rules:
- Internal anchors:
[label](#section-name)must point at a heading that exists in the current file. Anchor IDs follow the project's slug rule (lowercase, hyphenated). - Relative file links:
[label](../path/file.md)must resolve to an existing file on disk. - External URLs: probe with
HEAD(orGETwhenHEADis rejected). Report 4xx/5xx and DNS failures. Time out at 5s — a slow site is reported as a WARNING, not BLOCKING. - Placeholder URLs: any link starting with
TODO,FIXME,example.com, orlocalhostoutside an explicit "examples only" section is BLOCKING. - Anchor changes inside the same MR: if this MR renames a heading, every link to that heading inside the repo must be updated in the same MR.
Give a score: X/10.
Call: complete_agent(jobId, "link-validity", "success")
Audit 3: terminology
Call: start_agent(jobId, "terminology")
Inline rules:
- Ubiquitous language: product, feature, and domain terms match the project glossary (or, lacking one, the most frequent form used across the repo). Synonyms drift is BLOCKING when it changes meaning, IMPORTANT when it only changes style.
- Banned terms: avoid "easy", "simple", "obvious", "just", "merely" — these are condescending. Avoid "blacklist/whitelist" — use "denylist/allowlist".
- Undefined acronyms: every acronym is expanded on first occurrence per file (e.g., "Merge Request (MR)").
- Product name capitalization: stay consistent with the canonical spelling (e.g.,
GitLab, notGitlaborgitlab). - Inclusive language: gender-neutral pronouns ("they") in generic examples; no idioms that exclude non-native readers.
Give a score: X/10.
Call: complete_agent(jobId, "terminology", "success")
Audit 4: freshness
Call: start_agent(jobId, "freshness")
Inline rules:
- Version pins: every concrete version cited in prose (e.g., "Node.js 18+") must match the live
package.jsonenginesfield and thedependenciesblock. Mismatch is BLOCKING. - Deprecated APIs: a docs reference to an API that has been deleted, renamed, or marked
@deprecatedin the source tree is BLOCKING. - Timestamps: "as of YYYY-MM-DD" lines older than 12 months are flagged as WARNING; older than 24 months as IMPORTANT.
- Roadmap items shipped: documentation that still says "planned" or "coming soon" for a feature already merged is BLOCKING.
- Removed configuration keys: any config field cited in prose must still be parsed by the loader.
Give a score: X/10.
Call: complete_agent(jobId, "freshness", "success")
Audit 5: examples-validity
Call: start_agent(jobId, "examples-validity")
Inline rules:
- Code blocks parse: every
```ts,```tsx, and```jsonblock parses with the current TypeScript/JSON parser. Syntax errors are BLOCKING. - Import paths resolve: an import path cited inside a code block must resolve in the current source tree (allowing for the example's package context).
import { foo } from '@/x/y.js'where@/x/y.tsdoes not exist is BLOCKING. - Function/method signatures: a called function in an example must still exist with a compatible signature. Removed exports are BLOCKING.
- CLI commands:
yarn <script>calls must still exist inpackage.json.reviewflow <command>calls must still exist in the CLI surface. - Sample output: when an example shows expected output, the output must still be the output the current code produces (this is BEST-effort — flag deviations as IMPORTANT, not BLOCKING, unless verifiable trivially).
Give a score: X/10.
Call: complete_agent(jobId, "examples-validity", "success")
Phase 3: Results Synthesis
Call: set_phase(jobId, "synthesizing")
After the 5 audits:
- Overall score: Weighted average of the 5 audits
- Summary table: Score + Verdict per audit
- Blocking corrections — what must be fixed before merge:
- Broken/unreachable links
- Stale references (deprecated APIs, removed configs, wrong versions)
- Terminology drift that changes meaning
- Code examples that no longer match the source
- Important corrections — to be done this week
- Improvements — for the backlog
- Positive observations
Pedagogical Lessons
MANDATORY: For each point raised, add a lesson:
### Point: [Problem title]
**Detected problem**: [Description]
**Pedagogical lesson**:
> "[Author quote]"
> — [Author or style guide]
**Explanation**: [How this rule applies]
**Practical application**: [How to fix it in this context]Authorized sources:
| Source | Domain |
| Diátaxis framework (Procida) | Documentation structure (tutorials, how-to, reference, explanation) |
| Google Developer Documentation Style Guide | Tone, voice, terminology |
| Microsoft Writing Style Guide | Inclusive language, accessibility |
| Write the Docs community guidelines | Heading hierarchy, link practices |
| OWASP Secure Coding Practices | When examples touch credentials |
Report Structure
# Documentation Review - MR [Number] ([Title])
**Date**: [YYYY-MM-DD]
**Reviewer**: Claude Code (Doc Mode)
**Branch**: `[branch-name]`
**Modified files**: [X] (+[additions]/-[deletions] lines)
---
## Executive Summary
| Audit | Score | Verdict |
|-------|-------|---------|
| **Markdown Quality** | X/10 | [Short verdict] |
| **Link Validity** | X/10 | [Short verdict] |
| **Terminology** | X/10 | [Short verdict] |
| **Freshness** | X/10 | [Short verdict] |
| **Examples Validity** | X/10 | [Short verdict] |
**Overall Score: X/10** - [Final verdict]
---
## Blocking Corrections (before merge)
- Broken/unreachable links
- Stale references (deprecated APIs, removed configs, wrong versions)
- Terminology drift that changes meaning
- Code examples that no longer match the source
## Important Corrections (this week)
[...]
## Improvements (backlog)
[...]
## Positive Observations
[...]
## Pre-Merge Checklist
[...]Inline Comments on Diffs
Same rules as the other review skills. Each blocking/important violation gets one POST_INLINE_COMMENT on the relevant diff line.
| Severity | Prefix |
| Blocking | [BLOCKING] |
| Important | [IMPORTANT] |
Body structure:
**[BLOCKING] Problem title**
`file.md:42`
Short factual description of the problem in 1-2 sentences.
**Fix**: Short solution with corrected text or link.Report Publishing
Call: set_phase(jobId, "publishing")
- Post inline comments FIRST.
- Save the MD in
/.claude/reviews/[YYYY-MM-DD]-MR-[ID]-doc-review.md. - Post the global report on the MR via
add_action(POST_COMMENT).
Recommended Skills for Corrections
| Detected issue | Skill to use |
| Major doc restructuring | /create-doc |
| Documentation index update | /docs-index |
| Stale reference cleanup | /update-docs |
| Full documentation audit | /audit-docs |
Exit Commands
Call: set_phase(jobId, "completed")
Global report posted on the MR: [comment URL]
Local copy: /.claude/reviews/[YYYY-MM-DD]-MR-[ID]-doc-review.md
Overall score: X/10
Inline comments posted in /diffs: X
Blocking: X
Important: X
Backlog improvements (global report only): X
[REVIEW_STATS:blocking=X:warnings=X:suggestions=X:score=X:categories=security=N,logic=N,performance=N,typeSafety=N,style=N,dependencies=N]
READ-ONLY MODE - No documentation modified
Recommended skills:
- /update-docs for stale reference cleanup
- /docs-index after major restructuringIMPORTANT: The [REVIEW_STATS:...] line is MANDATORY for automated tracking.
Category breakdown (categories= segment)
Classify every finding (blocking + important + suggestion) into exactly one of the six dashboard categories, then emit the count per category in the marker. The six counts must sum to blocking + warnings + suggestions. Map by the audit that raised the finding:
| Audit that raised the finding | Category |
| Terminology, examples-validity (incorrect content) | logic |
| Markdown-quality, link-validity, freshness | style |
Use the internal keys exactly: security, logic, performance, typeSafety, style, dependencies. This skill has no Security, Performance, Type Safety or Dependency audits, so security, performance, typeSafety and dependencies are normally 0. Set any unused key to 0. Unknown keys are ignored by the tracker.
Final reminder: This skill NEVER modifies documentation. The report and inline comments are posted via MCP actions so the author can make corrections.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

