review-skill

スキルレビュー

エージェントスキルの PR をレビューし、構造上の妥当性、設計品質、マーケットプレイスとの整合性を確認します。

引数

• $ARGUMENTS：レビュー結果の出力先ファイルパス（必須。呼び出し元のハーネスまたはユーザーから渡されます）
• --base <branch>：差分比較のベースブランチ（デフォルト：main）

ワークフロー

Step 1: 引数を解析する

$ARGUMENTS から出力先パスを抽出します。パスが指定されていない場合は、.review-output.md をデフォルトとして使用します。--base が指定されている場合はその値を抽出し、指定されていない場合は main をデフォルトとして使用します。

Step 2: 変更されたスキルを特定する

git diff --name-only $(git merge-base HEAD <base>)..<HEAD> | grep -E '(SKILL\.md|skills/[^/]+/)'

変更されたファイルをスキルディレクトリごとにグループ化します。一意のスキルディレクトリごとに、レビュー対象とします。スキルファイルが変更されていない場合は、出力先パスに「スキルファイルは変更されていません」と書き込み、停止します。

Step 3: 変更された各スキルを最初から最後まで読む

変更されたスキルごとに、次の手順を実行します。

1. SKILL.md 全体を読む（差分行だけではありません）
2. スキルディレクトリ内のすべてのファイルを読む（参照ファイル、スクリプト）
3. 親プラグインディレクトリを確認し、その plugin.json を探す

Step 4: 構造チェックを実行する（信頼度：高）

references/structural-checks.md に記載されたすべてのチェックを適用します。これらは二択で合否を判定でき、違反は明確です。

構造上の違反は機械的に検証できるため、信頼度は高です。

Step 5: 設計チェックを実行する（信頼度：中）

references/design-checks.md に記載されたすべてのチェックを適用します。判断が必要なため、単に自分なら別の方法を選ぶというだけでは指摘せず、問題が明確な場合に限ってフラグを付けます。

設計上の問題は主観的な評価を伴うため、信頼度は中です。

Step 6: マーケットプレイスチェックを実行する（信頼度：高）

references/marketplace-checks.md に記載されたすべてのチェックを適用します。これらのチェックでは、スキルが所属するマーケットプレイスに正しく統合されているかを確認します。

マニフェストファイルを読めば検証できるため、マーケットプレイスに関する違反の信頼度は高です。

Step 7: 検証プロトコルを読み込み、適用する

review-verification-protocol スキルを読み込みます。指摘を報告する前に、次の点を検証します。

1. 差分のコンテキストだけでなく、実際のスキルの内容を読んだ
2. その問題は実在し、単なるスタイル上の好みではない
3. その問題は一般的なコードレビュー上の懸念ではなく、スキルファイルに当てはまる
4. 問題を裏付ける具体的な行を示せる

検証できない指摘は削除します。

Step 8: 出力を書き込む

ステップ 1 で指定した出力先パスに、以下の正確な形式で指摘を書き込みます。

出力形式

## Review Summary

[1-2 sentence overview of findings across all reviewed skills]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters for skill quality or marketplace health
   - Fix: Specific recommended fix
   - Confidence: HIGH

### Major (Should Fix)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...
   - Confidence: HIGH|MEDIUM

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...
   - Confidence: HIGH|MEDIUM

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...
   - Confidence: MEDIUM

## Verdict

Ready: Yes | No | With fixes 1-N
Rationale: [1-2 sentences — only Critical and Major items block approval]

各問題には連番を付けます。各問題には Confidence: HIGH|MEDIUM を含めます。判定では軽微および情報提供の項目を無視します。

重大度の基準

Critical（マージをブロック）

• YAML フロントマターが無効、または存在しない（スキルを読み込めない）
• 必須の name フィールドまたは description フィールドがない
• SKILL.md が 500 行を超えている（パフォーマンスが低下する）
• マーケットプレイス内の既存スキルと名前が重複している

Major（修正すべき）

• name が形式ルールに違反している（ケバブケースではない、長すぎる、予約語である）
• description に「内容」または「使用タイミング」の要素がない、人称が誤っている、または 1024 文字を超えている
• 入れ子になった参照チェーン（別の参照を参照する参照）
• 説明が曖昧すぎて、正確に呼び出すことができない
• 形式テンプレートや例のない構造化出力
• ファイル参照に Windows 形式のパスを使用している

Minor（改善推奨）

• 時間に依存する内容（ハードコードされた日付、「最近」、「新しい」など）
• スキルファイル間で用語が一貫していない
• SKILL.md の内容が密であるにもかかわらず、段階的な情報開示が使用されていない
• ワークフローに検証手順がない
• 相互参照の欠落（SKILL.md が存在しないファイルにリンクしている）

Informational（参考情報）

• 既存のマーケットプレイススキルとのトリガーキーワードの重複
• 追加の参照ファイルに関する提案
• 説明の具体性を高める機会
• スクリプトに --help がない、または対話型プロンプトを使用している

再レビューのルール

修正が適用された後の再レビューでは、次の点に従ってください。

1. 以前に指摘した問題が正しく修正されたかどうかのみを確認します
2. 以前の問題と関係のない新たな指摘を追加しないでください
3. 修正されていない Minor 項目は受け入れ、再度指摘しないでください
4. 再レビューの目的は検証であり、新たな問題の発見ではありません

参考資料

• 構造チェック：references/structural-checks.md — フロントマター、命名、行数制限、パス形式
• 設計チェック：references/design-checks.md — 説明の品質、段階的な情報開示、自由度
• マーケットプレイスチェック：references/marketplace-checks.md — 名前の衝突、plugin.json の一貫性、トリガーの重複