md-review

Overview of md-review skill

What md-review does

md-review is a Code Review presentation skill that turns a markdown PR writeup into a single-file, two-column HTML review. It expects review markdown with unified diff fenced blocks and severity-tagged comments such as > [!BLOCKER], > [!MAJOR], > [!MINOR], or > [!NIT]. The output places the rendered diff on the left, annotation cards on the right, a findings jump-nav at the top, and a mandatory named reviewer footer.

Best-fit users and workflows

The md-review skill is best for teams that already write structured code review notes in markdown and want a portable HTML artifact for sharing, archiving, or handing off outside a PR platform. It fits engineering leads, reviewers, documentation maintainers, and agent workflows that convert PR analysis into a polished review page. It is especially useful when review severity, line anchoring, and accessibility matter more than a plain markdown summary.

What makes md-review different

Unlike a generic “make this review pretty” prompt, md-review has a defined pipeline: diff_parser.py extracts unified diff hunks, annotation_extractor.py attaches severity callouts to the nearest preceding diff block, and review_html_renderer.py produces the final HTML. The repository also documents rendering choices in references/diff_rendering_canon.md, references/pr_annotation_ux.md, and references/severity_coding.md, which makes the output more predictable than ad hoc LLM formatting.

Key adoption constraints

The main blocker is input shape. md-review is not for ordinary markdown pages, release notes, or narrative reports without diff hunks. It refuses to render without an explicit reviewer name, and it is designed not to encode severity with color alone; badges include icons and aria-label text for WCAG 1.4.1. If your source does not contain real unified diffs, route the task to a document-rendering skill instead.

How to Use md-review skill

md-review install and repository files to inspect

For Claude-compatible skill managers, install from the GitHub repository path, for example:

npx skills add alirezarezvani/claude-skills --skill md-review

After install, read SKILL.md first to understand invocation rules, then inspect these files before relying on it in production:

• scripts/diff_parser.py for accepted diff fence formats and --infer-diff
• scripts/annotation_extractor.py for callout parsing and attachment behavior
• scripts/review_html_renderer.py for required renderer flags such as --reviewer
• assets/md_review_template.html for the final page structure
• references/severity_coding.md for default and custom severity tiers

Prepare input that md-review can parse

A strong md-review usage pattern starts with markdown that keeps each finding close to the diff it describes:

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None

[!BLOCKER]
This can retry indefinitely if the provider never returns. Add a bounded timeout.

Use `diff` fenced blocks when possible. The parser can infer some untagged fences only when `--infer-diff` is used, but explicit fences reduce ambiguity. Put general comments before any diff only if you want them rendered as unanchored comments.

### Invoke md-review in an agent workflow

The skill can be triggered when a markdown-html orchestrator classifies input as `REVIEW`, or directly with `/cs:md-review`. A complete prompt should provide the source markdown, the reviewer name, and any severity convention changes:

```text
/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

If using the scripts directly, the practical flow is: parse diff blocks into JSON, extract annotations against those hunks, then render HTML with --reviewer. The scripts are Python stdlib-only, which makes them easier to run in locked-down CI or local automation.

Practical output-quality tips

For better anchoring, place each callout immediately after the relevant diff block. For better triage, reserve BLOCKER for must-fix issues and avoid labeling every concern as MAJOR. For better scanability, write the first sentence of each annotation as the decision point, because the jump-nav uses short previews. If your team uses different labels, pass a custom four-tier convention in most-severe-to-least-severe order, such as critical,important,suggestion,nit.

md-review skill FAQ

Is md-review for Code Review only?

Yes. md-review for Code Review is intentionally narrow: it converts markdown PR reviews with diff hunks and severity annotations into an HTML review page. It is not a general markdown site generator, not a PR diff generator, and not a substitute for writing the review itself.

What happens if my markdown has no diff blocks?

That is a poor fit. The skill’s core layout depends on unified diff hunks, line numbers, additions, deletions, and annotation attachment. Without diff blocks, the result would be misleading, so the intended behavior is to refuse or route the task to a document-oriented markdown-to-HTML skill.

How is md-review better than a normal prompt?

A normal prompt may produce attractive HTML, but it will often invent layout rules, miss line-number conventions, or rely on color-only severity cues. md-review uses concrete parsing and rendering scripts, a documented two-column review UX, and explicit accessibility constraints. That makes it better when consistency and review semantics matter.

Is md-review beginner-friendly?

It is beginner-friendly if you already understand markdown code fences and unified diffs. Beginners who only have prose comments may need to first generate or paste a real PR diff. The easiest starting point is to run the sample modes in the scripts, then adapt the sample markdown structure to your own review.

How to Improve md-review skill

Improve md-review inputs before rendering

The fastest way to improve md-review output is to improve the source review. Include file paths in standard unified diff headers, preserve @@ hunk headers, and keep enough context lines for reviewers to understand the change. Use one finding per callout where possible; combining unrelated issues in a single MAJOR card makes the jump-nav less useful.

Avoid common failure modes

Common failures include missing --reviewer, malformed diff fences, severity labels outside the configured convention, and annotations placed far away from the diff they reference. Another subtle issue is using severity as tone rather than priority. A harshly worded style preference should still be NIT; a calmly worded correctness issue may be BLOCKER.

Iterate after the first HTML output

After the first render, inspect three things: whether every finding appears in the top jump-nav, whether annotations attach to the intended hunks, and whether unanchored comments are truly general comments. If an annotation lands in the wrong place, move it closer to the relevant diff block rather than trying to fix the HTML manually.

Customize without breaking the review model

Use customization for team conventions, not for weakening the structure. A custom severity list is reasonable if your organization uses labels like critical, important, suggestion, and nit. Changing the output into a prose report, hiding severity icons, or removing the reviewer footer undermines what md-review is designed to guarantee: accountable, accessible, diff-centered review output.