skill-reviewer Skill | Agent Skills

skill-reviewer

既存スキルの内容妥当性を、蓄積したベストプラクティスに基づいて検証するスキル。スキルの構造・記述品質・設計意図の明確さを多角的にチェックし、具体的な改善提案を行う。

スコープ

検証対象:

SKILL.md（frontmatter + 本文）
ディレクトリ構成（scripts/, references/, assets/, evals/, agents/）
bundled resources の内容品質と SKILL.md からの参照整合性

対象外:

スキルの実行テスト（実際にスキルを動かしての動作検証）
他スキルとの重複・競合分析
description のトリガー精度テスト

引数

skill-reviewer スキル [スキルパス]

スキルパスを指定すると単一スキル検証
パス省略時はユーザーに確認
ディレクトリパスを指定すると配下の全スキルを一括検証（各スキルに SKILL.md があるものを対象）

ワークフロー

Phase 1: 対象スキルの特定と読み込み

引数またはユーザー入力からスキルパスを特定
SKILL.md を読み込む
ディレクトリ構成を把握（どんなファイル・サブディレクトリがあるか）
bundled resources があれば読み込む
「タスク実行型」か「知識補強型」か、或いはその両方か、を判定する

Phase 2: チェックリスト検証の実行

references/checklist.md を読み込み、チェックリストに沿って検証を実行する。検証項目はチェックリストに定義されたもののみを使用し、独自の項目を追加しない。

検証は以下の6カテゴリで行う（カテゴリ6は Phase 3 で実行）:

構造検証 — frontmatter、ファイル構成、progressive disclosure
記述品質 — 指示の明確さ、why の説明、書き方パターン
description 品質 — トリガー条件の網羅性、pushy さ
リソース整合性 — 参照の存在確認、不要ファイルの検出
設計妥当性 — スコープの適切さ、汎用性と具体性のバランス
ベストプラクティス準拠 — 外部ベストプラクティス情報との整合性（Phase 3 で実行、スキップ可能）

各チェック項目は Pass / Warn / Fail の3段階で判定する:

Pass: 問題なし
Warn: 改善の余地あり（動作に支障はないが品質向上が見込める）
Fail: 明確な問題あり（修正を推奨）

Phase 3: ベストプラクティス準拠検証の実行

ベストプラクティス情報を取得し、対象スキルがそれらに準拠しているかを検証する。

手順:

references/best-practices.md の存在を確認する
ファイルが存在しない、または空の場合 → この Phase をスキップして Phase 4 へ進む
取得できたベストプラクティス内容を元に、対象スキルの SKILL.md および bundled resources を検証する

検証の観点:

取得したベストプラクティスが推奨する設計パターンに沿っているか
ベストプラクティスが警告するアンチパターンに該当していないか
ベストプラクティス固有の推奨事項で、対象スキルに適用可能なものが守られているか

判定基準: Phase 2 と同じ Pass / Warn / Fail の3段階を適用する。

Pass: ベストプラクティスに準拠している
Warn: 準拠していないが、スキルの目的上許容できる乖離
Fail: 明確にベストプラクティスに反しており、品質への影響が大きい

検証結果はレポートの「6. ベストプラクティス準拠」カテゴリとして出力する。各項目にはどのURLのどの推奨事項に基づく判定かを明記する。

Phase 4: レポート出力

以下のフォーマットで会話内に出力する:

## スキル検証レポート: {skill-name}

### サマリー
- 検証日: YYYY-MM-DD
- 対象パス: /path/to/skill
- 総合スコア: {Pass数}/{全項目数} (Warn: {数}, Fail: {数})
- ベストプラクティス検証: {実施 / スキップ（理由）}

### Fail 項目（要修正）
| # | カテゴリ | チェック項目 | 詳細 | 改善提案 |
|---|---------|------------|------|---------|

### Warn 項目（改善推奨）
| # | カテゴリ | チェック項目 | 詳細 | 改善提案 |
|---|---------|------------|------|---------|

### Pass 項目
（折りたたみ可能なリストで表示）

### 総合所見
{スキル全体を通じた所見と優先度付き改善提案}

一括検証の場合は、各スキルの個別レポートに加えて横断サマリーも出力する。

Phase 5: 修正確認ループ

レポート出力後、推奨案を含む複数の選択肢を提示して次のアクションを確認する:

選択肢:

修正を実施する — レポートの指摘事項に基づいてスキルを修正する
完了（レポートのみ） — レポートを出力して終了する

「修正を実施する」が選択された場合

推奨案を含む複数の選択肢を提示して修正の進め方を確認する
- どの指摘項目を修正するか（全件 / 選択）
- 修正方針について確認が必要な項目があれば合わせて質問する
確認内容に基づいて対象スキルのファイルを修正する
修正完了後、Phase 2 → Phase 3 → Phase 4 を再実行する（Phase 1 の読み込みは修正済みファイルを対象にする）
再度 Phase 5 に戻り、同じ選択肢を提示する

この 確認 → 修正 → 再検証 → 確認 のサイクルは、ユーザーが「完了（レポートのみ）」を選択するまで再帰的に繰り返す。

ただし、ユーザーの依頼に「レビュー結果に基づいて改善して」「問題があれば修正して」のように修正許可が明示されている場合は、同じ指摘について追加確認を挟まず、影響の小さい改善から実施する。仕様判断・大規模変更・外部状態の変更が必要な項目だけ確認に戻す。

再実行時の注意

再実行のレポートには (再検証 #{回数}) をサマリーに付記する
前回の指摘が解消されたかを明示的に記載する（例: 「前回 Fail だった 2-02 が Pass に改善」）
新たに発生した指摘があればそれも報告する

検証における判断指針

厳格すぎない検証を心がける

「ALWAYS/NEVER の多用よりも why を説明する」というアプローチ。検証でも同じ精神で臨む。形式的なルール違反を機械的に指摘するのではなく、そのスキルが意図した目的を効果的に達成できるかという観点で判断する。

例えば:

500行を少し超えていても、内容が密度高く整理されていれば Warn 止まり
frontmatter に optional フィールドがなくても、不要なら Pass
references/ がなくても、SKILL.md 単体で完結しているなら問題なし

コンテキストを読む

スキルの種類によって最適な構造は異なる。

シンプルなワンショットスキル → SKILL.md のみで十分
複雑なマルチステップスキル → references/ や scripts/ があるべき
ツール連携スキル → compatibility フィールドが重要

スキルの目的と複雑さに応じて、何が必要で何が過剰かを判断する。

Agent Skills: skill-reviewer

Install this agent skill to your local

Skill Files