MDXG Redline — md-review Human Review Loop Skill
Route AI-generated Markdown to a human redliner and bring comments back as structured JSON, running the full review loop automatically.
Scripts only generate HTML and poll for files — minimal scope; cleanup is dry-run by default requiring explicit --yes; permissions confined to two wrapper prefixes with documented rationale. Deducted for: npx dependency pulling an unpinned npm package at runtime (supply-chain surface), automatic browser launch without explicit confirmation, the --clean --yes destructive path requiring a separate permission rule, and unverified publisher (unknown identity, not penalized per se).
SKILL.md documents extensive failure modes (headless browser, Chromium-only API, timeout handling, sourceLine drift fallback), wrapper scripts are coherent, evals. is present. Deducted for: static review cannot execute key paths, evals require a human reviewer in the loop, wait-feedback.sh does not validate the path argument, and error feedback when npx fetch fails is not documented.
Clear use/do-not-use boundaries, explicit trigger patterns (auto, slash, natural language), documented browser compatibility constraints. Deducted for: core function depends on npx/npm registry which may be unreachable from mainland China networks, no declared Chinese-language support (docs are English/Japanese), and the workflow inherently requires a human reviewer present, narrowing the usable scenario range.
Well-layered docs (workflow, rationale, troubleshooting, permissions config), MIT license, consistent naming between skill and CLI. Deducted for: no CHANGELOG or version history visible in scope, the wrapper path assumption ties to a fragile .claude/settings.local. prefix-match convention that is install-dependent, and no explicit maintenance/update responsibility statement.
The end-to-end loop (generate → review → apply comments) is logically coherent with a principled application policy (fix vs question vs conflict), offering real marginal value over manual CLI invocation. Deducted for: static review cannot verify outputs work as described; comment application relies on Claude's judgment rather than deterministic transformation; the round-trip requires human reviewer patience which may limit practical adoption.
evals. and concrete eval fixtures exist, CI workflows run check/test/build, and rationale sections explain design choices. Deducted for: evals are not executable in static review, provided evals are hand-constructed fixtures rather than automated passing tests, no committed test suite shown covering the skill's own wrapper scripts, and no third-party execution evidence.
- Static source review only; nothing was executed and all scores are low-confidence estimates.
- Runtime depends on npx fetching mdxg-redline from the npm registry, which may be unreachable from mainland China networks; pre-install locally if needed.
- Write feedback. is Chromium-only; Safari/Firefox reviewers must use the export/copy fallbacks.
- --clean --yes performs destructive deletion; always run the dry-run first and review candidates.
- The workflow requires a human reviewer in the browser loop, and comment application depends on Claude's interpretation — verify before batch-applying.
- Publisher identity is unverified by the FollowSkills registry; treat provenance as unknown.
What does this skill do, and when should you use it?
MDXG Redline is a fully in-browser, single-HTML-file Markdown review tool that turns a human's inline comments into structured feedback. with headingPath and sourceLine precision. The companion md-review skill automates the whole loop end-to-end: it generates the review HTML, polls in the background for the exported feedback, applies each comment back into the Markdown, and can start another round. It implements nearly all MUST/SHOULD items of the MDXG Viewer (read-only rendering) profile as a third-party implementation of vercel-labs/mdxg. It fits any workflow where a human must sign off on AI-written documents.
Runs npx mdxg-redline <input.md> to generate <name>-<docHash>-review.html and auto-open the browser; waits for the reviewer to highlight text, comment, and click Write feedback. (File System Access API); polls for feedback. in the background via wait-feedback.sh at 5-second intervals with a 30-minute default timeout; parses comments[], locating each by sourceLine with a quote-grep fallback, and edits the Markdown with the Edit tool; optionally bulk-cleans review artifacts with the --clean subcommand. The review HTML renders Shiki syntax highlighting (~235 languages), Mermaid diagrams, KaTeX math, GFM footnotes, virtual stacked pages, and WASD keyboard navigation.
What are this skill's strengths and limitations?
- Fully local and privacy-friendly: standalone/CLI builds never send body text or comments anywhere; the online edition only allows an allowlisted ?url= raw fetch
- Feedback is structured JSON with headingPath, sourceLine, and quote, letting agents apply comments precisely
- docHash (first 16 hex of SHA-256) mechanically pairs each review HTML with its feedback file per round
- Polling uses run_in_background, freeing Claude's main turn for parallel work during review
- Strong rendering: Shiki highlighting, Mermaid, KaTeX, footnotes, virtual pages, WASD navigation, smartphone support
- Write feedback. depends on the File System Access API — Safari/Firefox reviewers must fall back to download-export or clipboard flows
- If Claude edits the Markdown mid-round, sourceLine drifts and the quote-grep fallback becomes essential (built in, but adds fragility)
- Default 30-minute polling timeout; longer reviews require a manual extension prompt
- Headless/SSH environments need --no-open or the HTTP-server mode (default port 51729); misconfigured devcontainer forwarding may block access
- No test suite or benchmarks are shown in the source; MDXG itself is a preview spec, and Images rendering is only Partial compliant
How do you install this skill?
In your project: gh skill install oubakiou/mdxg-redline md-review --agent claude-code --scope project, or npx skills add oubakiou/mdxg-redline --skill md-review --agent claude-code --yes. The skill lives at skills/md-review/SKILL.md in the repo. The CLI itself runs via npx mdxg-redline (requires Node.js). Alternatively download standalone.html from GitHub Releases for offline review. Add the three Bash prefix rules documented in the source to .claude/settings.local. permissions.allow.
How do you use this skill?
Tell Claude something like "send docs/spec.md out for review" or run /md-review path/to/markdown.md. Flow: the skill calls request-review.sh to generate the review HTML and captures REVIEW_HTML / FEEDBACK_JSON paths from stdout → the reviewer comments in the browser → wait-feedback.sh polls in the background (timeout overridable, default 1800s) → Claude reads feedback. and applies comments to the Markdown → it asks whether to run another round, clean up, or finish. Note: Write feedback. requires a Chromium-based browser; scripts must be invoked via bash with a project-root-relative path (gh skill install strips the execute bit, and permission rules match by prefix).
How does this skill compare with similar options?
The source states it is a third-party implementation of vercel-labs/mdxg that conforms to the MDXG specification without affiliation to Vercel Labs, layering inline commenting and structured feedback JSON export on top of the read-only Viewer conformance level.