This tool evaluates documentation for clarity and accuracy through iterative improvement cycles.
Install
mkdir -p .claude/skills/review-docs && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5181" && unzip -o skill.zip -d .claude/skills/review-docs && rm skill.zipInstalls to .claude/skills/review-docs
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Review and improve documentation with parallel evaluation and iterative improvement loop.Key capabilities
- →Evaluate documentation style and voice
- →Verify technical accuracy against source code
- →Track issues in a state file
- →Iteratively improve documentation
How it works
The skill uses parallel agents to evaluate style and content, tracks findings in a state file, and applies fixes iteratively until scores reach target levels.
Inputs & outputs
When to use review-docs
- →Refine technical documentation
- →Check documentation for clarity
- →Improve project README files
About this skill
Review documentation
This skill runs an evaluation and improvement loop on a documentation file.
Target: $ARGUMENTS
Relevant skills: write-docs
Workflow overview
┌──────────────────────────────────────────────────────────────┐
│ INITIALIZE: Create state file to track issues │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ EVALUATE (parallel) │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ Style Agent │ │ Content Agent │ │
│ │ (readability+voice) │ │ (completeness+accuracy) │ │
│ └─────────────────────┘ └─────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ UPDATE STATE: Add new issues, verify fixed issues │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ SUMMARIZE: Present findings, ask user for next step │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────┼──────────────────┐
↓ ↓ ↓
[User: improve] [User: complete] [User: done]
↓ ↓ ↓
┌──────────────────┐ ┌──────────────────┐ EXIT
│ IMPROVE │ │ COMPLETE │
│ (fix issues) │ │ (fix all, exit) │
└──────────────────┘ └──────────────────┘
↓ ↓
LOOP → EVALUATE EXIT
State file
Create a state file in the scratchpad directory to track all issues across rounds. This prevents re-discovering the same issues and allows verification of fixes.
Path: <scratchpad>/review-<filename>.md
Format:
# Review tracker: [filename]
## Issue tracker
Status values: `pending` | `fixed` | `verified-fixed` | `not-fixed` | `wont-fix`
| ID | Issue | Type | Status | Round | Notes |
| --- | ------------- | --------------------------- | -------------- | ----- | ---------------- |
| 1 | [description] | Style/Accuracy/Completeness | pending | 1 | [details] |
| 2 | [description] | Accuracy | verified-fixed | 1 | Fixed in round 1 |
| 3 | [description] | Completeness | wont-fix | 2 | Out of scope |
## Round history
### Round 1
- Style: X/10, Voice: X/10, Completeness: X/10, Accuracy: X/10
- **Total: X/40**
Status definitions:
pending: Issue discovered, not yet addressedfixed: Improvement agent claims to have fixed it, needs verificationverified-fixed: Evaluation confirmed the fix was applied correctlynot-fixed: Evaluation found the fix wasn't applied correctlywont-fix: False alarm, out of scope, or intentional (e.g., completeness issues that require documentation expansion)
Step 1: Initial evaluation
For the first round, launch two subagents in parallel using the Task tool:
// Single message with two Task tool calls:
Task(subagent_type="general-purpose", model="opus", prompt="Style evaluation...")
Task(subagent_type="general-purpose", model="opus", prompt="Content evaluation...")
Style agent prompt (round 1)
Evaluate documentation style for: $ARGUMENTS
Read the shared guides relative to this skill directory, then read the target document:
1. `../../VOICE.md`
2. `../shared/docs-guide.md`
3. $ARGUMENTS
Score these dimensions (0-10):
READABILITY - How clear and easy to understand is the writing?
- Clear, direct sentences
- Logical flow between sections
- Appropriate use of code snippets and links
- No unnecessary jargon
VOICE - How well does it follow the writing guide?
- Confident assertions (no hedging)
- Active voice, present tense
- No AI writing tells (hollow importance, trailing gerunds, formulaic transitions)
- Appropriate tone (expert-to-developer)
- Sentence case headings
Important! Include as many high-priority fixes as needed.
Return in this exact format:
STYLE REPORT: [filename]
READABILITY: [score]/10
- [specific issue or strength]
- [specific issue or strength]
VOICE: [score]/10
- [specific issue or strength]
- [specific issue or strength]
PRIORITY FIXES:
1. [Most important style issue]
2. [Second most important]
3. [Third most important]
4. ...
Content agent prompt (round 1)
Evaluate documentation content for: $ARGUMENTS
Read $ARGUMENTS, then verify claims against the source code in packages/editor/ and packages/tldraw/.
Score these dimensions (0-10):
COMPLETENESS - How thorough is the coverage?
- Overview establishes purpose before mechanism
- Key concepts explained with enough depth
- Illustrative code snippets where needed
- Links to relevant examples in apps/examples (if applicable)
ACCURACY - Is the technical content correct?
- Code snippets are syntactically correct and use valid APIs
- API references match actual implementation
- Described behavior matches the code
- No outdated information
For accuracy issues, include file:line references to the source code.
Important! Include as many high-priority fixes as needed. Make sure that all accuracy issues are flagged.
Return in this exact format:
CONTENT REPORT: [filename]
COMPLETENESS: [score]/10
- [specific issue or strength]
- [specific issue or strength]
ACCURACY: [score]/10
- [specific issue with file:line reference if inaccurate]
- [specific issue or strength]
PRIORITY FIXES:
1. [Most important content issue]
2. [Second most important]
3. [Third most important]
4. ...
After round 1, create the state file with all discovered issues.
Step 2: Summarize and prompt user
After both agents return, synthesize their reports into a summary:
## Evaluation: [filename]
| Dimension | Score | Key issue |
| ------------ | ----- | ----------- |
| Readability | X/10 | [one-liner] |
| Voice | X/10 | [one-liner] |
| Completeness | X/10 | [one-liner] |
| Accuracy | X/10 | [one-liner] |
| **Total** | X/40 | |
### Priority fixes
1. [Combined priority 1 from both reports]
2. [Combined priority 2]
3. [Combined priority 3]
4. [Combined priority 4]
5. [Combined priority 5]
6. ...
Then ask the user using AskUserQuestion:
- Improve: Make improvements based on findings, then re-evaluate
- Complete and finish: Fix all remaining issues and exit (no re-evaluation)
- Done: Exit the loop without making changes
Step 3: Triage (before improvement)
Before running the improvement agent, review the pending issues with the user. Mark completeness issues that require adding new sections as wont-fix - these are documentation expansion, not review fixes.
Per AGENTS.md guidance:
"Do what has been asked; nothing more, nothing less." "Don't add features, refactor code, or make 'improvements' beyond what was asked."
The review skill improves existing content. Adding new sections is a separate task.
Step 4: Improve
Launch a single improvement agent targeting only pending issues:
Task(subagent_type="general-purpose", model="opus", prompt="Improve documentation...")
Improvement agent prompt
Improve documentation based on specific tracked issues: $ARGUMENTS
Fix ONLY these pending issues:
| ID | Issue | Type | Notes |
|----|-------|------|-------|
[paste pending issues from state file]
Instructions:
1. Read `../../VOICE.md` and `../shared/docs-guide.md` relative to this skill directory
2. Read $ARGUMENTS
3. For each accuracy fix:
- Read the source file referenced in the notes
- Verify the correct API/behavior from the source
- Apply the fix based on what the source code actually shows
5. Apply style fixes
6. Run prettier: yarn prettier --write $ARGUMENTS
DO NOT:
- Add new sections
- Expand the document
- Fix issues not in the list above
Return a summary:
CHANGES MADE:
| ID | Fix applied | Verification |
|----|-------------|--------------|
| X | [description] | [source file:line checked] |
| Y | [description] | n/a |
After improvement, update the state file to mark issues as fixed.
Step 4b: Complete and finish (alternative to Step 4)
If the user selects "Complete and finish", fix all remaining pending issues without re-evaluating. This is useful when the evaluation is satisfactory and the user wants to apply fixes and move on.
Workflow:
- Run triage (same as Step 3) to mark out-of-scope items as
wont-fix - Launch the improvement agent (same prompt as Step 4)
- Update state file to mark issues as
fixed - Exit the loop - do not re-evaluate
This path trusts the improvement agent to apply fixes correctly and skips the verification cycle. Use when:
- The issues are straightforward style fixes
- Time is limited and re-evaluation isn't worth the cost
- Scores are already acceptable and only minor polish remains
Step 5: Verification evaluation
For subsequent rounds, evaluation agents verify fixes AND find new issues:
Style agent prompt (verification)
Verify fixes and evaluate documentation: $ARGUMENTS
Read the state file first: [path to state file]
Then read the shared guides relative to this skill directory and the target document:
1. `../../VOICE.md`
2. `../shared/docs-guide.md`
3. $ARGUMENTS
Your job:
1. VERIFY fixes marked as "fixed" in the state file - confirm they were actually applied
2. Score style dimensions (do NOT re-flag wont-fix issues)
3. Flag only NEW issues not already in the state file
VERIFY THESE FIXES:
[paste fixed style issues from state file]
Return in this format:
VERIFICATION REPORT:
| ID | Status | Notes |
|----|--------|-------|
| X
---
*Content truncated.*
When not to use it
- →When adding new sections or expanding documentation scope
Limitations
- →Does not support adding new content sections
- →Requires manual user input to proceed through loops
How it compares
It uses a formal verification loop with state tracking rather than a single-pass review.
Compared to similar skills
review-docs side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| review-docs (this skill) | 1 | 3mo | No flags | Intermediate |
| docs-write | 22 | 6mo | No flags | Beginner |
| content-research-writer | 15 | 10mo | No flags | Beginner |
| doc-coauthoring | 16 | 8mo | No flags | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by tldraw
View all by tldraw →You might also like
docs-write
metabase
Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).
content-research-writer
ComposioHQ
Assists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership.
doc-coauthoring
anthropics
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
research-grants
davila7
Write competitive research proposals for NSF, NIH, DOE, and DARPA. Agency-specific formatting, review criteria, budget preparation, broader impacts, significance statements, innovation narratives, and compliance with submission requirements.
teams-channel-post-writer
daymade
Creates educational Teams channel posts for internal knowledge sharing about Claude Code features, tools, and best practices. Applies when writing posts, announcements, or documentation to teach colleagues effective Claude Code usage, announce new features, share productivity tips, or document lessons learned. Provides templates, writing guidelines, and structured approaches emphasizing concrete examples, underlying principles, and connections to best practices like context engineering. Activates for content involving Teams posts, channel announcements, feature documentation, or tip sharing.
write-docs
tldraw
Writing SDK documentation for tldraw. Use when creating new documentation articles, updating existing docs, or when documentation writing guidance is needed. Applies to docs in apps/docs/content/.