skill-review

Files (11)

• README.md
• README_ja.md
• SKILL.md
• openai.yaml · agents/
• CHANGELOG.md · references/
• criteria.md · references/
• trigger-test.md · references/
• check_criteria.sh · scripts/
• check_description_length.sh · scripts/
• criteria.baseline · scripts/
• update_changelog.sh · scripts/

SKILL.md (first lines)

# skill-review

## 目的

Agent skill (SKILL.mdとその付属ファイル)を評価基準に沿って点検し、
**観点ごとの判定・根拠・修正案**をレポートするSkill。
レポートをユーザーに返したあとは、どれを修正するかをユーザーに判断してもらい、修正の適用はユーザーの別途依頼を待つ。

## Arguments

- `<path>`: 評価対象のskillディレクトリまたはSKILL.mdのパス(複数指定可)
- 指定が無い場合は、リポジトリ内のskillを探索してユーザーに指定か全件を対象にするかを求める。
- `--propose`: 評価を行わず、同じ会話で控えた基準候補の確認だけを行う (「レポート後の基準候補」を参照)

## 評価観点

各観点の詳細な判定基準と良い例・悪い例は [references/criteria.md](references/criteria.md)を参照すること。
評価時は必ずcriteria.mdを読んでから判定する。
基準の変更履歴は [references/CHANGELOG.md](references/CHANGELOG.md) にある。判定に使う基準はcriteria.mdだけで、CHANGELOG.mdは旧基準の痕跡の検出と根拠の表示にだけ使う。

観点1〜11の評価前に、Agent Skills仕様への適合性を別枠のゲートとして検証する。
詳細はcriteria.mdの「仕様チェック」を参照すること。

| #   | 観点               | 要約                                                                                                                                         |
| --- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | 目標と境界         | 目的が冒頭で簡潔に述べられ、descriptionの書き写しでなく、発動条件と矛盾していないか                                                          |
| 2   | description品質    | 発動条件が容易に判断でき、簡潔な表現になっていて、trigger testで期待どおりに選ばれるか                                                       |
| 3   | コマンド例の量     | 例が最小限で、形式・順序・境界ケースの明確化に限定されているか                                                                               |
| 4   | 完了条件           | 何をもって成功とするか、および副作用 (commit / push / 外部への書き込み) の範囲が定義されているか                                             |
| 5   | 早期リターン       | 前提が満たされない場合に即終了する手順があるか                                                                                               |
| 6   | 自己完結性         | 必要ファイルをskill内に含むか。通常skillは他skillへ言及・委譲していないか。オーケストレーションskillは連結先・順序・引き継ぎ・後始末が明確か |
| 7   | 簡潔さ             | 本文が冗長でないか(SKILL.md本文は目安500行以下)                                                                                              |
| 8   | 分割               | 長いテンプレート・例・詳細ドキュメントがreferences/等に分離され、参照が1段までか                                                             |
| 9   | 可読性             | 人間がメンテナンスしやすい構成・見出し・表現か                                                                                               |
| 10  | 鮮度               | 参照しているコマンド・パス・ファイルが実在し、付属スクリプトがLinter・Formatterを通り動作するか                                              |
| 11  | クライアント互換性 | モデル固有機能への依存に対象環境か代替手段があり、手順の具体性が作業の壊れやすさに釣り合っているか                                           |

`allowed-tools`などのクライアント固有frontmatterの構文と最小権限は仕様チェックで判定する。
未対応クライアントで無視されること自体は減点しない。

判定は観点ごとに次の4値とする。

- **合格**: 基準を満たしている
- **要改善**: 基準を満たしていない(根拠と修正案を必ず添える)
- **該当なし**: その観点が対象skillに適用されない(例: クライアント固有設定を持たないskillに対する観点11)
- **判定保留**: 観点は適用されるが、判定に必要な証拠を取得できない(不足している証拠を明記する)

## 作業手順

### 0. 基準の自己点検

criteria.mdが変わったのにCHANGELOG.mdに記録が無い状態を、評価の前に検出する。
同じ会話で控えた基準候補が残っていれば、先に「レポート後の基準候補」の確認を行ってからこの手順に入る。

1. `bash scripts/check_criteria.sh` を実行する。scriptは記録時点のcriteria.mdのコピー (`scripts/criteria.baseline`) と現在のcriteria.mdを比較する。パスは自分の位置から解決するので、skillの配置場所やgit管理の有無を問わない。出力の1行目が結果で、`DIFF` のときは2行目以降にbaselineからの差分が続く
2. 結果で分岐する
   - `UP_TO_DATE` → 手順1へ進む
   - `INITIALIZED` → baselineが無かったので現在のcriteria.mdを記録済みとして保存した。その旨を1行報告して手順1へ進む
   - `DIFF` → 差分を読み、変更ごとにCHANGELOG.mdの形式でentryの下書き (種別・変更・理由・痕跡・修正) を作る。既存entryに記録済みの変更と、評価対象から確認できる痕跡を持たない変更は除く。下書きは5項目すべてを提示してAskUserQuestionでユーザーに確認し、特に理由は差分から推測せず回答から書く。確認したentryを `bash scripts/update_changelog.sh --add` の標準入力へ渡して追記する (scriptがbaselineも更新する)。記録すべき変更が1つも無ければ `bash scripts/update_changelog.sh --sync` でbaselineだけを更新する。記録が終わってから手順1へ進む

### 1. 対象の列挙

引数のパス、または全件評価モードならリポジトリ内のSKILL.mdを列挙する。
指定パスが存在しない、またはSKILL.mdが1件も見つからない場合は、その旨をユーザーに報告して終了する。

descriptionの競合検査用に、評価対象と同じリポジトリまたはskill配置ルートにある他skillの`name`と`description`も列挙する。
比較範囲を特定できない場合は、競合部分を判定保留にする。

### 2. 仕様チェック

[references/criteria.md](references/criteria.md)の「仕様チェック」に従い、frontmatterとSKILL.mdの基本構造を検証する。
利用可能なら対象仕様のvalidatorを実行し、利用できなければ同じ要件を手作業で確認する。
descriptionの文字数は [scripts/check_description_length.sh](scripts/check_description_length.sh) に対象パスを渡して判定する (`FAIL` が出た行を根拠にする)。

- 全要件を満たす: **仕様適合**
- 1件でも違反がある: **仕様不適合**

仕様不適合でも、判定可能な観点1〜11の評価は続ける。

### 3. 評価

skillごとに以下を行う。

1. SKILL.md本文と付属ファイル(references/等)を読む
2. [references/criteria.md](references/criteria.md)の基準に沿って観点1〜11を判定する
3. 「要改善」には**該当行の引用**を根拠として付け、具体的な修正案を書く
4. 観点10(鮮度)は、本文中のファイルパス・コマンド名の実在を確認し、付属スクリプトには `shellcheck` と `shfmt -d` (Pythonは `ruff check` と `ruff format --check`。Formatterのオプションはリポジトリのformatter設定に従い、無ければ既定で実行する) を適用したうえで、副作用の無い引数 (`--help`、dry-run、読み取り専用の操作) で実行して判定する。書き込みや投稿を伴う引数では実行しない
5. 観点2(description品質)は、列挙した他skillのdescriptionと発動条件を比較し、[references/trigger-test.md](references/trigger-test.md) の手順でtrigger testを行う
6. CHANGELOG.mdのentryごとに「痕跡」を評価対象から探し、種別で扱いを分ける
   - `強化` の痕跡 → 該当観点の要改善に含め、根拠に「旧基準由来 (CHANGELOG YYYY-MM-DD <観点>)」と書く
   - `廃止` の痕跡 → 減点せず、レポートの「削除してよい箇所」に列挙する
   - `緩和` の痕跡 → 指摘しない

推測で判定しない。根拠を示せない場合は「要改善」ではなく判定保留として報告する。

### 4. レポート

skillごとに以下の形式で出力する。

```text
## skills/example-skill/

### 仕様チェック

判定: 仕様適合

| 観点 | 判定 | 根拠 |
| --- | --- | --- |
| 1. 目標と境界 | 合格 | 冒頭の「目的」がdescriptionより詳細で矛盾なし |
| 2. description品質 | 要改善 | トリガーフレーズが無い |
| 10. 鮮度 | 判定保留 | コマンドの実在を確認できる環境が無い |
| ... | ... | ... |

### trigger test

| 場面 | 期待 | Claude Code | Codex |
| --- | --- | --- | --- |
| 1. 「PR作って」と依頼された | example-skill | 5/5 (example-skill 5) | 5/5 (example-skill 5) |
| 2. 作成済みPRのレビューを頼まれた | なし | 2/5 (example-skill 3 / なし 2) | 5/5 (なし 5) |

From mjun0812/skills, MIT.

More from mjun0812/skills