md-review

md-review skill 概览

md-review 的作用

md-review 是一个面向 Code Review 展示的 skill，可以把 markdown 格式的 PR review 文档转换成单文件、双栏布局的 HTML review 页面。它要求输入的 review markdown 包含统一格式的 diff fenced blocks，并使用带严重级别的评论标记，例如 > [!BLOCKER]、> [!MAJOR]、> [!MINOR] 或 > [!NIT]。输出页面会把渲染后的 diff 放在左侧、批注卡片放在右侧，顶部提供 findings jump-nav，并在页脚强制显示具名 reviewer。

最适合的用户和工作流

md-review skill 最适合已经用 markdown 编写结构化 code review 备注，并希望生成一个便于分享、归档或在 PR 平台之外交接的便携 HTML 成果物的团队。它适用于 engineering leads、reviewers、documentation maintainers，以及把 PR 分析转换为精致 review 页面的一类 agent workflow。尤其当 review 的严重级别、行级锚定和可访问性比普通 markdown 摘要更重要时，md-review 会更有价值。

md-review 的不同之处

md-review 不是一个泛泛的“把这个 review 做得好看一点”的 prompt，而是有明确的处理流水线：diff_parser.py 提取 unified diff hunks，annotation_extractor.py 将严重级别 callouts 关联到最近的前置 diff block，review_html_renderer.py 生成最终 HTML。仓库还在 references/diff_rendering_canon.md、references/pr_annotation_ux.md 和 references/severity_coding.md 中记录了渲染选择，因此输出比临时让 LLM 排版更可预测。

采用 md-review 的关键限制

主要门槛在输入结构。md-review 不适合普通 markdown 页面、release notes，或没有 diff hunks 的叙述型报告。它在没有明确 reviewer name 时会拒绝渲染，并且设计上不会只用颜色表达严重级别；badges 会包含 icons 和 aria-label 文本，以满足 WCAG 1.4.1。如果你的源内容不包含真实的 unified diffs，应改用面向文档渲染的 skill。

如何使用 md-review skill

md-review 安装与需要检查的仓库文件

对于兼容 Claude 的 skill managers，可以从 GitHub repository path 安装，例如：

npx skills add alirezarezvani/claude-skills --skill md-review

安装后，先阅读 SKILL.md 了解调用规则；在生产环境依赖它之前，再检查以下文件：

• scripts/diff_parser.py：了解支持的 diff fence 格式以及 --infer-diff
• scripts/annotation_extractor.py：了解 callout 解析和关联行为
• scripts/review_html_renderer.py：了解必需的 renderer flags，例如 --reviewer
• assets/md_review_template.html：了解最终页面结构
• references/severity_coding.md：了解默认和自定义严重级别层级

准备 md-review 能解析的输入

高质量的 md-review 使用方式，通常从一份 markdown 开始：每个 finding 都应尽量贴近它所描述的 diff：

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None
```

> [!BLOCKER]
> This can retry indefinitely if the provider never returns. Add a bounded timeout.

尽可能使用 diff fenced blocks。只有在启用 --infer-diff 时，parser 才能推断部分未标记的 fences；显式 fences 能减少歧义。如果你希望某些通用评论以未锚定评论形式渲染，可以把它们放在任何 diff 之前。

在 agent workflow 中调用 md-review

当 markdown-html orchestrator 将输入分类为 REVIEW 时，可以触发该 skill；也可以直接使用 /cs:md-review。一个完整的 prompt 应提供源 markdown、reviewer name，以及任何严重级别约定变更：

/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

如果直接使用 scripts，实际流程是：先把 diff blocks 解析为 JSON，再基于这些 hunks 提取 annotations，最后用带 --reviewer 的 renderer 生成 HTML。这些 scripts 只依赖 Python stdlib，因此更容易在受限的 CI 或本地自动化环境中运行。

提升输出质量的实用建议

为了获得更好的锚定效果，把每个 callout 立即放在相关 diff block 后面。为了更便于 triage，把 BLOCKER 留给必须修复的问题，不要把所有顾虑都标成 MAJOR。为了提升可扫读性，每条 annotation 的第一句话应直接写出决策点，因为 jump-nav 会使用简短预览。如果你的团队使用不同标签，可以传入按“最严重到最不严重”排序的自定义四级约定，例如 critical,important,suggestion,nit。

md-review skill 常见问题

md-review 只适用于 Code Review 吗？

是的。面向 Code Review 的 md-review 有意保持窄范围：它把包含 diff hunks 和严重级别 annotations 的 markdown PR reviews 转换为 HTML review 页面。它不是通用 markdown site generator，不是 PR diff generator，也不能替代你撰写 review 本身。

如果我的 markdown 没有 diff blocks 会怎样？

这并不适合使用 md-review。该 skill 的核心布局依赖 unified diff hunks、line numbers、additions、deletions，以及 annotation attachment。没有 diff blocks 时，结果可能具有误导性，因此预期行为是拒绝处理，或将任务路由到面向文档的 markdown-to-HTML skill。

md-review 比普通 prompt 好在哪里？

普通 prompt 也许能生成好看的 HTML，但经常会自行编造布局规则、遗漏行号约定，或只依赖颜色表达严重级别。md-review 使用具体的 parsing 和 rendering scripts、文档化的双栏 review UX，以及明确的可访问性约束。当你更看重一致性和 review 语义时，它更可靠。

md-review 对新手友好吗？

如果你已经理解 markdown code fences 和 unified diffs，那么它对新手是友好的。只有纯文字评论的新手，可能需要先生成或粘贴真实 PR diff。最容易的起步方式是先运行 scripts 中的 sample modes，再把示例 markdown 结构改造成自己的 review。

如何改进 md-review skill

渲染前先改进 md-review 输入

提升 md-review 输出的最快方式，是先提升源 review 的质量。在标准 unified diff headers 中包含 file paths，保留 @@ hunk headers，并保留足够的 context lines，方便 reviewers 理解改动。尽可能每个 callout 只写一个 finding；把互不相关的问题塞进同一张 MAJOR card，会削弱 jump-nav 的价值。

避免常见失败模式

常见失败包括缺少 --reviewer、diff fences 格式错误、severity labels 不在已配置的 convention 内，以及 annotations 距离其引用的 diff 太远。还有一个更隐蔽的问题：把 severity 当成语气而不是优先级。措辞严厉的样式偏好仍然应是 NIT；语气平和的正确性问题也可能是 BLOCKER。

首次 HTML 输出后继续迭代

第一次渲染后，重点检查三件事：每个 finding 是否都出现在顶部 jump-nav 中，annotations 是否关联到了预期的 hunks，以及 unanchored comments 是否确实是通用评论。如果某条 annotation 落到了错误位置，应把它移动到相关 diff block 附近，而不是手动修改 HTML。

在不破坏 review 模型的前提下自定义

自定义应服务于团队约定，而不是削弱结构。如果你的组织使用 critical、important、suggestion 和 nit 这样的标签，自定义 severity list 是合理的。把输出改成纯文字报告、隐藏 severity icons，或移除 reviewer footer，都会削弱 md-review 设计上要保证的内容：可追责、可访问、以 diff 为中心的 review 输出。