md-review

md-review skill 概覽

md-review 的用途

md-review 是一個 Code Review 簡報型 skill，可將 markdown PR 審查稿轉成單一檔案、雙欄式 HTML review。它預期輸入的審查 markdown 會包含 unified 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 workflows。當 review 嚴重度、行號錨定與 accessibility 比單純的 markdown 摘要更重要時，md-review 尤其有價值。

md-review 的差異化之處

md-review 不是一般「把這份 review 變漂亮」的 prompt，而是有明確 pipeline：diff_parser.py 會擷取 unified diff hunks，annotation_extractor.py 會把 severity callouts 附加到最接近的前一個 diff block，review_html_renderer.py 則產出最終 HTML。repository 也在 references/diff_rendering_canon.md、references/pr_annotation_ux.md 與 references/severity_coding.md 中記錄渲染選擇，因此輸出會比臨場用 LLM 排版更可預期。

主要導入限制

最大的門檻是輸入格式。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 安裝與應檢視的 repository 檔案

若使用 Claude-compatible skill managers，可從 GitHub repository path 安裝，例如：

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

安裝後，請先閱讀 SKILL.md 了解 invocation rules；在正式環境依賴它之前，也建議檢視下列檔案：

• scripts/diff_parser.py：確認支援的 diff fence formats 與 --infer-diff
• scripts/annotation_extractor.py：了解 callout parsing 與 attachment behavior
• scripts/review_html_renderer.py：確認必要的 renderer flags，例如 --reviewer
• assets/md_review_template.html：查看最終頁面結構
• references/severity_coding.md：了解預設與自訂 severity tiers

準備 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。parser 在使用 --infer-diff 時可以推斷部分未標記的 fences，但明確標記可降低歧義。只有在你希望一般留言被渲染成未錨定 comments 時，才把這類留言放在任何 diff 之前。

在 agent workflow 中呼叫 md-review

當 markdown-html orchestrator 將輸入分類為 REVIEW 時，可以觸發此 skill；也可以直接使用 /cs:md-review。完整 prompt 應提供來源 markdown、reviewer name，以及任何 severity convention 調整：

/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 parse 成 JSON，再根據這些 hunks extract annotations，最後用 --reviewer render HTML。這些 scripts 只使用 Python stdlib，因此更容易在受限的 CI 或本機自動化環境中執行。

實用的輸出品質建議

為了讓錨定更準確，請把每個 callout 放在相關 diff block 的正後方。為了讓 triage 更清楚，請把 BLOCKER 保留給必須修正的問題，避免把每個 concern 都標成 MAJOR。為了提升 scanability，每則 annotation 的第一句應寫成決策重點，因為 jump-nav 會使用短版預覽。如果團隊使用不同 labels，可以傳入自訂四層級 convention，順序需由最嚴重到最不嚴重，例如 critical,important,suggestion,nit。

md-review skill 常見問題

md-review 只適用於 Code Review 嗎？

是。md-review for Code Review 的定位刻意收斂：它會把含有 diff hunks 與 severity annotations 的 markdown PR reviews 轉成 HTML review page。它不是一般 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，但常會自行發明 layout rules、漏掉 line-number conventions，或只用顏色表達 severity。md-review 使用具體的 parsing 與 rendering scripts、已文件化的雙欄 review UX，以及明確的 accessibility constraints。當一致性與 review semantics 很重要時，這會更可靠。

md-review 對新手友善嗎？

如果你已經理解 markdown code fences 與 unified diffs，md-review 算是容易上手。若新手手上只有文字評論，可能需要先產生或貼上真正的 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 輸出後持續迭代

第一次 render 後，請檢查三件事：每個 finding 是否都出現在頂部 jump-nav、annotations 是否附加到預期的 hunks，以及 unanchored comments 是否真的屬於一般性 comments。如果 annotation 落在錯誤位置，應把它移到更靠近相關 diff block 的地方，而不是手動修改 HTML。

在不破壞 review model 的前提下自訂

自訂應用於團隊慣例，而不是削弱結構。如果你的組織使用 critical、important、suggestion、nit 這類 labels，自訂 severity list 是合理的。把輸出改成 prose report、隱藏 severity icons，或移除 reviewer footer，都會削弱 md-review 原本要保證的特性：可追責、具 accessibility、以 diff 為中心的 review output。