Markdown Review Converter
FreeTransform markdown code reviews into structured HTML.
Free · Opens the source repo
What Markdown Review Converter does
The Markdown Review Converter skill is designed to streamline the process of converting markdown pull request (PR) write-ups into a well-structured, single-file HTML review. This skill specifically targets markdown documents that contain diff blocks and severity annotations, producing a two-column layout that enhances readability and usability. On the left, users will find the unified diff, while the right side displays severity-tagged annotation cards, ensuring that important findings are highlighted and easily accessible.
This tool is particularly beneficial for developers and teams engaged in code reviews, as it enforces a structured format that aligns with best practices outlined in industry standards. The converter operates through a series of Python scripts that parse markdown input, extract relevant annotations, and render the final HTML output. Each annotation is carefully linked to the corresponding diff hunk, providing context and clarity for reviewers.
The skill enforces several hard rules to maintain quality and accessibility. For instance, it requires a named reviewer to be specified, ensuring accountability in the review process. Additionally, it adheres to WCAG 1.4.1 standards, making sure that severity badges include not just color but also icons and aria-labels for screen readers. This attention to detail helps teams produce reviews that are not only informative but also accessible to all stakeholders.
Overall, the Markdown Review Converter is an essential tool for any development team looking to improve their code review process. By transforming markdown PR write-ups into a structured HTML format, it enhances collaboration, clarity, and compliance with established coding standards.
When to use it
Use this skill when you have a markdown PR write-up with diff blocks and severity annotations that need to be converted into a structured HTML review.
When not to use it
Avoid using this skill for markdown documents that do not contain diff blocks or are shorter than 100 lines, as it is designed specifically for code reviews.
What you can build with it
Team Code Review
When conducting team code reviews, use this skill to convert markdown PR write-ups into a structured HTML format for better clarity.
Accessibility Compliance
Ensure your code review outputs are accessible by utilizing the skill's adherence to WCAG standards, making reviews inclusive for all team members.
Custom Severity Labels
If your team has specific severity conventions, customize the output using the skill's options to align with your internal guidelines.
How to install Markdown Review Converter
View source1. Install with the skills CLI
npx skills add alirezarezvani/claude-skills/md-review --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by alirezarezvanimd-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
# 1. Parse markdown → diff hunks JSON
python3 markdown-html/skills/md-review/scripts/diff_parser.py \
--input <path>.md --output hunks.json
# 2. Extract severity-tagged annotations, attach to nearest preceding hunk
python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
--input <path>.md --diff-blocks hunks.json --output annotations.json
# 3. Render 2-col HTML (--reviewer is mandatory — refuses without)
python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
--diff-blocks hunks.json --annotations annotations.json \
--reviewer "Jane Doe" --title "PR #123: Add retry logic" \
--output review.html
What gets rendered
- Top jump-nav — every annotation with severity badge + 80-char preview + jump link; severity counts in the heading ("3 BLOCKER · 2 MAJOR · 1 NIT")
- 2-column hunk rows — unified diff on the left (per-line old/new line numbers, +/− marks, addition/deletion background tint from design-system tokens), annotation cards on the right (color + icon + aria-label per WCAG 1.4.1)
- Approval bar — if
LGTMmarkers are present and no severity annotations, a success-tinted "LGTM — no findings flagged" bar - General comments — annotations not attached to any hunk render at the bottom in their own section
- Reviewer footer — mandatory; refuses to render without
--reviewer - Responsive — 2-col collapses to stacked on viewports < 900px
Hard rules
--revieweris mandatory. A code review must name a human reviewer. Refuses with exit 3 otherwise. Mirrors research-ops's "named owner" discipline.- Refuses if no hunks present. No
--- a/file+@@ ... @@blocks means this isn't a code review — refuses with exit 4 and recommendsmd-document. - Refuses input < 100 lines. Markdown wins below the threshold (Shihipar).
- Refuses without onboarding. Same gate as every converter.
- Severity is never color-only. Each badge ships color + icon +
aria-label+ text. WCAG 1.4.1 enforced at the renderer level. - Single-file output. All CSS inline. Only external is Google Fonts CSS. No Prism in md-review (diff coloring conflicts with syntax highlighting).
- Custom severity convention.
--severity-convention "critical,important,suggestion,nit"swaps tier names; position 0 is most severe. Default is BLOCKER / MAJOR / MINOR / NIT (Google Code Review Developer Guide).
Forcing-question library (Matt Pocock grill discipline)
- Who is the named reviewer? Recommended: the user signing off on the review. Canon: research-ops named-owner pattern; SWE at Google ch. 9.
- Which severity convention applies — default (BLOCKER/MAJOR/MINOR/NIT) or custom? Recommended: default unless your team has a documented alternative. Canon: Google Code Review Developer Guide.
- Are annotations anchored to specific hunks, or are some general? Recommended: anchor everything you can; general goes to the unanchored section. Canon: SWE at Google ch. 9 — "Comments must reference a specific line".
- What's the PR title for the
<title>and header? Recommended: the actual PR / commit title. Canon: docs-as-context-for-readers. - Should
LGTMmarkers ship as the approval bar? Recommended: yes if there are no severity annotations; otherwise the findings take precedence.
Distinct from
md-document— that converter renders prose + tables + code + callouts. This one renders diff hunks + margin annotations.md-slides— that converter splits on---boundaries. This one is a single-page artifact.- GitHub PR comments — those are a thread. This is a single-author snapshot artifact.
Output artifact
{default_output_dir}/review-{slug}.html (path resolved by orchestrator's output_path_resolver.py; collision suffix -2, -3, … by default).
References
- Shihipar — Claude Code HTML output (Medium, 2026), Tier 2 use case
- Software Engineering at Google (Manshreck & Wright, O'Reilly 2020), ch. 9 "Code Review"
- Google Code Review Developer Guide — severity convention source
- WCAG 2.2 §1.4.1 — color-not-sole-signal enforcement
- See
references/for full citations (diff_rendering_canon, severity_coding, pr_annotation_ux)
Frequently asked questions about Markdown Review Converter
Similar skills
Quality Playbook Generator
Run comprehensive quality audits on any codebase.
PR Draft Summary
Automate PR summary generation for openai-agents-python.
Final Release Review
Streamline your release candidate audits with ease.
Unit Test Vue Pinia
Efficiently write and review unit tests for Vue 3 applications.
Slang Shader Expert
Optimize and integrate Slang shaders with ease.
Telemetry Standards
Ensure consistent event tracking in Supabase Studio.