AGENT SKILL

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 encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing.

License 许可
MIT
最近更新
2026-06-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
md-review
tags
[ "markdown", "html", "code-review", "diff", "severity", "annotations", "single-file", "design-system", "wcag-1.4.1" ]
author
Alireza Rezvani
license
MIT
version
2.10.2
description
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 encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing.
compatible_tools
[ "claude-code", "codex-cli", "cursor", "antigravity", "opencode", "gemini-cli" ]

03 SKILL.md 正文

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

# 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 LGTM markers 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

  1. --reviewer is mandatory. A code review must name a human reviewer. Refuses with exit 3 otherwise. Mirrors research-ops's "named owner" discipline.
  2. Refuses if no hunks present. No --- a/file + @@ ... @@ blocks means this isn't a code review — refuses with exit 4 and recommends md-document.
  3. Refuses input < 100 lines. Markdown wins below the threshold (Shihipar).
  4. Refuses without onboarding. Same gate as every converter.
  5. Severity is never color-only. Each badge ships color + icon + aria-label + text. WCAG 1.4.1 enforced at the renderer level.
  6. Single-file output. All CSS inline. Only external is Google Fonts CSS. No Prism in md-review (diff coloring conflicts with syntax highlighting).
  7. 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)

  1. Who is the named reviewer? Recommended: the user signing off on the review. Canon: research-ops named-owner pattern; SWE at Google ch. 9.
  2. 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.
  3. 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".
  4. What's the PR title for the <title> and header? Recommended: the actual PR / commit title. Canon: docs-as-context-for-readers.
  5. Should LGTM markers 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)

04 同仓库更多 Skills

haresh-sai06
haresh-sai06/SapSynk-AI

youtube-full

Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private/age-restricted videos.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

x-twitter-growth

X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

workflow-builder

Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

webinar-marketing

When the user wants to plan, promote, run, or improve a webinar or virtual event to generate and convert demand. Use when the user mentions 'webinar,' 'virtual event,' 'online event,' 'live demo,' 'virtual summit,' 'workshop,' 'masterclass,' 'fireside chat,' 'roundtable,' 'registration funnel,' 'show-up rate,' 'attendance rate,' 'webinar promotion,' 'webinar follow-up,' or 'on-demand webinar.' Also use when they have a webinar that isn't converting — low registrations, low show-up, or attendees who don't buy — and want to diagnose and fix it. Covers the full funnel: registration, promotion, show-up, live engagement, live-to-close, and post-event nurture. Distinct from launch-strategy (full product launches) and email-sequence (lifecycle nurture) — this is the end-to-end webinar/event motion. NOT for in-person field events logistics, and NOT for generic lifecycle email (use email-sequence).

★ 0
haresh-sai06
haresh-sai06/SapSynk-AI

vpe-advisor

VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing → screen → onsite → offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) — VPE owns delivery operations and how the team ships.

★ 0