| name | mdreview |
| description | Interactively review a full Markdown document with a human. Use when the user wants to comment on a whole Markdown file (plan, design doc, README, essay, PRD) in a browser and have those comments returned for AI revision. Triggers on phrases like "review this markdown", "let me comment on the doc", "open a review for <file>.md". |
mdreview Skill
Review a full Markdown document interactively with a human, then apply their comments.
Workflow
-
Save the Markdown to a concrete file path if it isn't on disk yet.
-
Run the CLI with the Bash tool's run_in_background: true — it blocks until the human finishes (multi-user: until the owner clicks Finish All), so a foreground run would hit the 120s Bash timeout and get killed mid-review. You're notified on exit; then read its stdout.
npx @mash/mdreview path/to/file.md
-
Tell the user: "Comment on the document in the browser, then click Finish Review or just close the tab."
-
On exit, read stdout (the review result) and apply the comments as human review instructions — the tool is read-only toward the file; you make the edits. Wrap them for the model, e.g. "The user reviewed the document and left these comments; revise the file accordingly, preserving the original intent unless a comment asks otherwise."
-
Ambiguous comment → smallest reasonable change. Big restructuring → offer another review pass.
stdout format
# Review comments for path/to/file.md
## Comment 1
Target: path/to/file.md:L12-L20
Heading: Architecture > CLI server
Selected text:
The CLI starts a local server...
Comment:
This explanation is too vague. Add the data flow.
If stdout is No comments were submitted., do not revise.
Options
npx @mash/mdreview doc.md --port 3456
npx @mash/mdreview doc.md --tailscale
MDREVIEW_NO_OPEN=1 npx @mash/mdreview doc.md
Multi-user (--tailscale)
Default is single-user (binds 127.0.0.1, you review alone, closing the tab finishes). For others to review too, add --tailscale: binds the tailnet IP, serves HTTPS, and prints an owner URL (yours) plus a reviewer URL to share — give reviewers the reviewer URL, not the owner one. Everyone's comments merge.
Ending a multi-user review. The owner ends it explicitly with Finish All (or Ctrl-C); merged comments print on exit. If the owner just closes their tab:
- No other reviewer still active (everyone else is done or has left) → the review auto-finishes within a few seconds and comments print on exit — same as single-user.
- A guest is still reviewing → the review stays open so the guest isn't cut off. The CLI logs to stderr:
owner tab closed, but N guest(s) are still reviewing … reopen the owner URL to continue: <url>.
When you (the skill) should act on this: the CLI runs in the background and you're notified on exit. If the user comes back before it exits and asks about the review, read the background run's stderr: if you see the owner tab closed … reopen the owner URL: <url> line, tell the user that guests are still active and offer that owner URL to rejoin (or offer to stop the run with Ctrl-C to finish now). Note the in-page Copy comments button is a separate manual fallback the user can use anytime.
