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-11-08
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

Tashima-Tarsh
Tashima-Tarsh/Disha6.6

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
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

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
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

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.

Skill与智能体开发
★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

wrap-up

Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says "wrap up", "close this out", "what do I own now", "give me the summary", "recap the agent", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained ./my-agent/agent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done.

★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

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.

Skill与智能体开发
★ 0
Tashima-Tarsh
Tashima-Tarsh/Disha6.6

weekly-review

Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.

★ 0