md-review

md-review skill の概要

md-review ができること

md-review は、markdown で書かれた PR レビューを、単一ファイルの 2 カラム HTML レビューに変換する Code Review 向けのプレゼンテーション skill です。入力として想定しているのは、unified diff の fenced block と、> [!BLOCKER]、> [!MAJOR]、> [!MINOR]、> [!NIT] のような重要度タグ付きコメントを含むレビュー markdown です。出力では、左側にレンダリング済み diff、右側に注釈カード、上部に findings へのジャンプナビゲーション、末尾に必須の記名レビュアーフッターが配置されます。

向いているユーザーとワークフロー

md-review skill は、すでに構造化されたコードレビューコメントを markdown で書いていて、共有・アーカイブ・PR プラットフォーム外への引き継ぎに使えるポータブルな HTML 成果物がほしいチームに向いています。エンジニアリングリード、レビュアー、ドキュメントメンテナー、PR 分析を整ったレビュー画面に変換する agent ワークフローと相性がよい skill です。特に、単なる markdown 要約よりも、レビューの重要度、行への紐づけ、アクセシビリティを重視する場合に役立ちます。

md-review の違い

一般的な「このレビューを見やすくして」というプロンプトとは異なり、md-review には明確な処理パイプラインがあります。diff_parser.py が unified diff の hunk を抽出し、annotation_extractor.py が重要度付き callout を直前の diff block に関連付け、review_html_renderer.py が最終的な HTML を生成します。リポジトリには references/diff_rendering_canon.md、references/pr_annotation_ux.md、references/severity_coding.md でレンダリング方針も記録されているため、場当たり的な LLM フォーマットよりも出力を予測しやすくなっています。

導入時の主な制約

最大の制約は入力形式です。md-review は、通常の markdown ページ、リリースノート、diff hunk を含まない説明中心のレポート向けではありません。明示的なレビュアー名がない場合はレンダリングを拒否します。また、重要度を色だけで表現しない設計になっており、バッジには WCAG 1.4.1 に配慮してアイコンと aria-label テキストが含まれます。ソースに本物の unified diff が含まれていない場合は、ドキュメントレンダリング向けの skill に回すべきです。

md-review skill の使い方

md-review のインストールと確認すべきリポジトリファイル

Claude 互換の skill manager では、たとえば次のように GitHub リポジトリパスからインストールします。

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: --reviewer などレンダラーで必須のフラグ
• assets/md_review_template.html: 最終ページの構造
• references/severity_coding.md: デフォルトおよびカスタムの重要度階層

md-review が解析できる入力を用意する

md-review をうまく使うには、各 finding を、それが説明している diff の近くに置いた markdown から始めるのが有効です。

# 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 block を使ってください。パーサーは `--infer-diff` を使った場合に限り、一部のタグなし fence を推測できますが、明示的な fence のほうが曖昧さを減らせます。全体コメントを diff に紐づかないコメントとして表示したい場合だけ、diff より前に置きます。

### agent ワークフローで md-review を呼び出す

この skill は、markdown-html orchestrator が入力を `REVIEW` と分類したときに起動できます。また、`/cs:md-review` で直接呼び出すこともできます。完全なプロンプトには、ソース markdown、レビュアー名、重要度ルールの変更があればその内容を含めます。

```text
/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]

スクリプトを直接使う場合の実用的な流れは、diff block を JSON に解析し、その hunk に対して注釈を抽出し、最後に --reviewer 付きで HTML をレンダリングする、という順序です。スクリプトは Python 標準ライブラリのみで動くため、制限の厳しい CI やローカル自動化でも実行しやすくなっています。

出力品質を上げる実践的なコツ

より正確に紐づけたい場合は、各 callout を関連する diff block の直後に置きます。トリアージしやすくするには、BLOCKER は必ず修正が必要な問題に限定し、あらゆる懸念を MAJOR にしないようにします。スキャンしやすさを高めるには、各注釈の最初の文に判断ポイントを書いてください。ジャンプナビゲーションでは短いプレビューが使われるためです。チームで別のラベルを使っている場合は、critical,important,suggestion,nit のように、最も重大なものから最も軽いものの順で 4 段階のカスタムルールを渡します。

md-review skill FAQ

md-review は Code Review 専用ですか？

はい。Code Review 向けの md-review は、意図的に用途を絞っています。diff hunk と重要度付き注釈を含む markdown の PR レビューを HTML レビューページに変換するためのものです。汎用の markdown サイトジェネレーターではなく、PR diff 生成ツールでもなく、レビューそのものを書く作業の代替でもありません。

markdown に diff block がない場合はどうなりますか？

その場合は適していません。この skill の中心となるレイアウトは、unified diff の hunk、行番号、追加行、削除行、注釈の関連付けに依存しています。diff block がないと結果が誤解を招くため、意図された挙動としては拒否するか、ドキュメント向けの markdown-to-HTML skill に回す形になります。

md-review は通常のプロンプトより何が優れていますか？

通常のプロンプトでも見栄えのよい HTML は作れるかもしれませんが、レイアウトルールを勝手に作ったり、行番号の扱いを外したり、重要度を色だけで表現してしまったりすることがよくあります。md-review は、具体的な解析・レンダリングスクリプト、文書化された 2 カラムのレビュー UX、明示的なアクセシビリティ制約を使います。そのため、一貫性とレビューの意味づけが重要な場面で有利です。

md-review は初心者にも使いやすいですか？

markdown の code fence と unified diff を理解しているなら、初心者にも扱いやすい skill です。文章のコメントしか持っていない初心者の場合は、先に実際の PR diff を生成または貼り付ける必要があります。最初はスクリプトのサンプルモードを実行し、そのサンプル markdown 構造を自分のレビューに合わせて調整するのが一番始めやすい方法です。

md-review skill を改善する方法

レンダリング前に md-review の入力を整える

md-review の出力を改善する最短の方法は、元になるレビューを改善することです。標準的な unified diff ヘッダーにファイルパスを含め、@@ hunk ヘッダーを残し、レビュアーが変更内容を理解できるだけの context 行を保持してください。可能な場合は、1 つの callout に 1 つの finding を書きます。関係のない問題を 1 枚の MAJOR カードにまとめると、ジャンプナビゲーションの有用性が下がります。

よくある失敗を避ける

よくある失敗には、--reviewer の指定漏れ、壊れた diff fence、設定済みルールに含まれない重要度ラベル、参照先の diff から離れすぎた注釈があります。もう 1 つ見落としやすい問題は、重要度を優先度ではなく語調として使ってしまうことです。きつい言い方のスタイル指摘でも内容が軽ければ NIT のままですし、穏やかな表現の正しさに関わる問題は BLOCKER になり得ます。

最初の HTML 出力後に反復する

最初にレンダリングしたら、3 点を確認します。すべての finding が上部のジャンプナビゲーションに表示されているか、注釈が意図した hunk に紐づいているか、紐づかないコメントが本当に全体コメントとして適切か、です。注釈が誤った場所に付いた場合は、HTML を手で直そうとするのではなく、関連する diff block の近くへ注釈を移動してください。

レビューモデルを壊さずにカスタマイズする

カスタマイズは、チームの運用ルールに合わせるために使うべきで、構造を弱めるために使うものではありません。組織で critical、important、suggestion、nit のようなラベルを使っているなら、カスタム重要度リストは妥当です。一方で、出力を文章中心のレポートに変える、重要度アイコンを隠す、レビュアーフッターを削除する、といった変更は、md-review が保証しようとしている「責任の所在が明確で、アクセシブルで、diff を中心にしたレビュー出力」という設計を損ないます。