md-review
Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review — unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to
Profile →npx skills add alirezarezvani/claude-skills --skill md-review --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# md-review — Code-review markdown → 2-column HTML The code-review converter from Tier 2 of Shihipar's essay ("Code Review and PR Writeups"). Takes a markdown PR writeup with diff blocks + severity callouts and produces a single-file HTML review with a jump-nav, 2-column diff + annotation layout, and a named reviewer footer. Three stdlib tools pipeline together: ``` diff_parser.py → annotation_extractor.py → review_html_renderer.py (md → diff hunks) (md → severity-tagged (hunks + annotations annotations attached + tokens → 2-col HTML) to nearest hunk) ``` ## When to invoke | Symptom | Action | |---|---| | `markdown-html-orchestrator` routes input as REVIEW | Invoke this skill | | User runs `/cs:md-review <path>.md` directly | Invoke this skill | | Input contains ` ```diff ` fenced blocks + `> [!MAJOR]`/`> [!BLOCKER]`/etc. callouts | Invoke this skill | | Input is a long-form spec / report (no diff blocks) | Route to `md-document` instead | | Input is a slide deck | Route to `md-slides` instead | | Input < 100 lines | Refuse (Shihipar threshold) | | Design-system not onboarded | Refuse; surface `/cs:design-system` | ## Pipeline ```bash # 1. Parse markdown → diff hunks JSON python3 m
- When to invoke
- What gets rendered
- Hard rules
- Forcing-question library (Matt Pocock grill discipline)
- Distinct from
- Output artifact
- References
python3 markdown-html/skills/md-review/scripts/diff_parser.py \ python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \ python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
What does the md-review skill do?
Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review — unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to
How do I install it?
Run `npx skills add alirezarezvani/claude-skills --skill md-review --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From alirezarezvani/claude-skills, a repository with 23,791 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.