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-07-04
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" ]

02 资源文件 7

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

motivatedc-creator
motivatedc-creator/Saafy

syllabus

Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') — even casual mentions with a syllabus attached should trigger this skill.

★ 0
motivatedc-creator
motivatedc-creator/Saafy

research

Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Use when the user makes any research request that doesn't obviously match a more-specific specialist skill (e.g., "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log.

★ 0
motivatedc-creator
motivatedc-creator/Saafy

pulse

Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis.

★ 0
motivatedc-creator
motivatedc-creator/Saafy

patent

Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope.

★ 0
motivatedc-creator
motivatedc-creator/Saafy

notebooklm

Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable.

★ 0
motivatedc-creator
motivatedc-creator/Saafy

litreview

Academic literature orientation skill that searches papers via free keyless APIs (PubMed E-utilities + OpenAlex) by default — with the Consensus MCP as an optional enhancement lane when connected — builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list — that's a plain PubMed/OpenAlex (or Consensus) query.

★ 0