Review Docs Agent Skill
Review and improve documentation with parallel evaluation and iterative improvement loop.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/tldraw/tldraw --skill review-docsWhat it tells the agent to use
found in the instruction textThe instruction itself
16 sections, as written by the authorReview 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. `../shared/writing-guide.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 `../shared/writing-guide.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. `../shared/writing-guide.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 | verified-fixed / not-fixed | [what you found] |
STYLE SCORES:
READABILITY: [score]/10
VOICE: [score]/10
NEW ISSUES (not already in state file):
- [issue] or "None found"
Content agent prompt (verification)
Verify fixes and evaluate documentation content: $ARGUMENTS
Read the state file first: [path to state file]
Then read $ARGUMENTS and verify claims against source code in packages/tldraw/.
Your job:
1. VERIFY accuracy fixes marked as "fixed" in the state file
2. Score content dimensions (do NOT re-flag wont-fix issues)
3. Flag only NEW accuracy issues not already in the state file
VERIFY THESE FIXES:
[paste fixed accuracy issues from state file]
Return in this format:
VERIFICATION REPORT:
| ID | Status | Notes |
|----|--------|-------|
| X | verified-fixed / not-fixed | [what you found in doc AND source] |
CONTENT SCORES:
COMPLETENESS: [score]/10 (score existing content only, ignore wont-fix items)
ACCURACY: [score]/10
NEW ACCURACY ISSUES (not already in state file):
- [issue with source file:line] or "None found"
After verification, update the state file with new statuses and any new issues.
Step 6: Loop
Continue the loop until:
- User chooses "Done" (exit without changes)
- User chooses "Complete and finish" (apply fixes, then exit)
- Scores reach acceptable levels (32/40 or higher)
- All issues are
verified-fixedorwont-fix
Notes
- The state file prevents re-discovering the same issues across rounds
- Evaluation agents verify previous fixes before scoring
wont-fixis appropriate for completeness issues requiring new sections- Accuracy verification is critical: The improvement agent must read actual source code before applying any accuracy fix
- Style and content evaluations always run in parallel for efficiency
Other skills for the same job
different authors, same section of the catalogue
Integration with protocols.io API for managing scientific protocols. This skill should be used when working with protocols.io to search, create, update, or publish protocols; manage protocol steps and materials; handle discussions and comments; organize workspaces; upload and manage files; or integrate protocols.io functionality into workflows. Applicable for protocol discovery, collaborative protocol development, experiment tracking, lab protocol management, and scientific documentation.
Analyzes job descriptions and generates tailored resumes that highlight relevant experience, skills, and achievements to maximize interview chances
Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.
Build and distribute Expo development clients locally or via TestFlight
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Data structure for annotated matrices in single-cell analysis. Use when working with .h5ad files or integrating with the scverse ecosystem. This is the data format skill—for analysis workflows use scanpy; for probabilistic models use scvi-tools; for population-scale queries use cellxgene-census.
Benchling R&D platform integration. Access registry (DNA, proteins), inventory, ELN entries, workflows via API, build Benchling Apps, query Data Warehouse, for lab data management automation.
Comprehensive molecular biology toolkit. Use for sequence manipulation, file parsing (FASTA/GenBank/PDB), phylogenetics, and programmatic NCBI/PubMed access (Bio.Entrez). Best for batch processing, custom bioinformatics pipelines, BLAST automation. For quick lookups use gget; for multi-service integration use bioservices.
How to use it
Take tldraw/review-docs from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.