From review-mode
Use when the user asks to open a Markdown file in Review Mode inside VS Code, or when iterating on a plan/document based on Review Mode annotations. Review Mode renders the file in a read-only WebView panel with annotation support. This does NOT open a web browser.
How this skill is triggered — by the user, by Claude, or both
Slash command
/review-mode:review-modeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Review Mode is a VS Code extension that renders Markdown files in a read-only WebView panel with threaded annotation support. Users can highlight lines, add comments, set priorities, and track statuses — all stored as JSON alongside the file.
Review Mode is a VS Code extension that renders Markdown files in a read-only WebView panel with threaded annotation support. Users can highlight lines, add comments, set priorities, and track statuses — all stored as JSON alongside the file.
This skill teaches you how to:
.md file in Review ModeThe skill is agent-agnostic — it works regardless of how the document was created.
Prerequisite: The review-mode MCP server must be configured in your MCP client settings. All operations use MCP tools — no CLI scripts or direct file reads are needed.
Command trigger: Treat /review-mode as an explicit user command to open the relevant Markdown plan/document in Review Mode via MCP (open_review), then confirm in chat that the file was created (if applicable) and opened in Review Mode.
If the plugin is installed correctly, the MCP server configuration is already registered (via .mcp.json). However, the review-mode-mcp executable itself must be installed on the system. If MCP tool calls fail with "tool not found", "server failed to start", or similar connection errors, the executable is likely missing.
Diagnosis: Run in the shell:
review-mode-mcp --version
If the command is not found, the MCP server is not installed.
Installation: The MCP server is distributed as a Python package and installed via uv:
uv is installed. If not, install it following the uv installation guide.uv tool install review-mode-mcp
review-mode-mcp --version
Important: If MCP tools fail unexpectedly, always check
review-mode-mcp --versionfirst before assuming a configuration issue.
The review-mode-mcp server provides the following tools:
open_review: Opens a file in Review Mode inside the editor.get_annotations: Returns the full array of annotations for a file.update_annotation: Updates the status or adds an agent reply to an annotation.list_reviewed_files: Lists all files in the workspace that have reviews.get_review_summary: Returns summary metadata for a file's review (counts, dates).create_annotation: Creates a new annotation on a specific line as the agent.Note on
workspaceparameter: While listed as optional in some schemas, it is highly recommended (and sometimes mandatory depending on server config) to provide theworkspaceparameter with the absolute or relative path to the root of the project to ensure the MCP server resolves paths correctly.
Use the open_review MCP tool:
open_review(
file_path="relative/path/to/file.md",
workspace="/path/to/project/root" # Recommended
)
This opens the file in Review Mode inside VS Code (or whichever editor the MCP server is configured for).
After opening, print a brief message in chat:
📋 The plan is ready for review in Review Mode.
Do NOT print the plan content in chat. The user will read it in the Review Mode panel.
When the user says they've added comments, or asks you to iterate on a plan, you MUST proactively read annotations using the MCP tools. Never ask the user to paste their annotations.
get_annotations(
file_path="relative/path/to/file.md",
workspace="/path/to/project/root"
)
This returns the full annotation array from the latest revision.
Print a brief summary:
📝 Found N annotations (X open, Y in-progress, Z resolved).
Only process annotations where status is "open" or "in-progress". Ignore "resolved" and "wont-fix".
Each annotation returned by get_annotations has this structure:
{
"id": "cc1rclk",
"startLine": 3,
"endLine": 3,
"textPreview": "The line of text this annotation refers to",
"priority": "none",
"status": "open",
"thread": [
{
"id": "2wu1xvj",
"text": "User's comment about this line",
"createdAt": "2026-04-28T17:10:19.928Z"
}
]
}
Fields:
| Field | Description |
|---|---|
id | Unique identifier for the annotation |
startLine / endLine | Line range in the markdown file (1-indexed) |
textPreview | The text content at the annotated line(s) |
priority | One of: none, low, medium, high, urgent |
status | One of: open, in-progress, resolved, wont-fix |
thread | Array of messages (the comment thread) |
Each message in thread[] has:
| Field | Description |
|---|---|
id | Unique message identifier |
text | The message content |
createdAt | ISO 8601 timestamp |
For each actionable annotation (status open or in-progress), decide one of three outcomes:
Edit the .md file to implement the change, then mark resolved:
update_annotation(
file_path="relative/path/to/file.md",
annotation_ids=["cc1rclk"],
status="resolved",
message="Implemented the requested change",
workspace="/path/to/project/root"
)
update_annotation(
file_path="relative/path/to/file.md",
annotation_ids=["cc1rclk"],
status="in-progress",
message="Which kind of description do you want? Verbose, concise, etc.?",
workspace="/path/to/project/root"
)
update_annotation(
file_path="relative/path/to/file.md",
annotation_ids=["cc1rclk"],
status="wont-fix",
message="Not feasible due to API limitations",
workspace="/path/to/project/root"
)
Pass multiple IDs at once:
update_annotation(
file_path="relative/path/to/file.md",
annotation_ids=["id1", "id2", "id3"],
status="resolved",
message="All comments addressed",
workspace="/path/to/project/root"
)
| Scenario | Action on .md file | MCP call |
|---|---|---|
| Fully addressable | Implement the change | status="resolved" |
| Needs clarification | No change (or partial) | status="in-progress", with question in message |
| Won't implement | No change | status="wont-fix", with reason in message |
The message is automatically prefixed with [AGENT] and added to the annotation's thread.
You can use these additional tools to manage the review workflow:
list_reviewed_files(workspace="/path/to/project/root")
Returns an array of files that have reviews, along with their revision_count, total_annotations, open_count, etc. Useful if you're not sure which file the user wants you to look at.
get_review_summary(file_path="relative/path/to/file.md", workspace="/path/to/project/root")
Returns metadata about a file's review state without pulling down the entire annotation array.
If you need to leave a comment or question on a specific line of the file for the user to see:
create_annotation(
file_path="relative/path/to/file.md",
line=42,
message="Should we consider refactoring this section?",
priority="medium",
status="open",
workspace="/path/to/project/root"
)
After processing all actionable annotations:
.md file to disk (same path as the original).update_annotation (see above).open_review(file_path="relative/path/to/file.md")
The extension will detect the file change and automatically create a new revision with migrated annotations.📋 Plan updated and ready for review. N comments resolved, M need your input.The user will trigger iteration with one of two intents:
get_annotations(file_path=<file>).md fileupdate_annotation(file_path=<file>, annotation_ids=[...], status="resolved", message="Done")open_review(file_path=<file>)get_annotations(file_path=<file>).md fileupdate_annotation(file_path=<file>, annotation_ids=[<all IDs>], status="resolved", message="All addressed")open_review(file_path=<file>)After a round where no annotations have status open and no new feedback was given, gently ask:
"The plan looks solid with no outstanding comments. Would you like to proceed with implementation, or do you want to review it further?"
Do NOT rush the user into implementation. Wait for explicit confirmation.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub aurelio-amerio/review-mode-plugin --plugin review-mode