skill-forge-review

スキルのレビューと検証

プロセス

ステップ 1：スキルファイルの特定

次の形式で入力を受け付けます：

• スキルディレクトリへのパス
• スキル名（~/.claude/skills/ 内を検索）
• GitHub リポジトリの URL

すべての .md ファイル、スクリプト、アセットファイルを読み込みます。

ステップ 2：構造の検証

プログラムによるチェックを実行するには、python scripts/validate_skill.py <path> を実行します。

手動で確認します：

• SKILL.md が存在する（大文字・小文字を厳密に区別）
• スキルフォルダ内に README.md がない
• フォルダ名が name フィールドと一致する
• 有効な kebab-case の命名である（1～64 文字）
• 名前に「claude」または「anthropic」が含まれていない

ステップ 3：フロントマターの監査

チェック項目	合格基準
名前の形式	kebab-case、1～64 文字、先頭または末尾がハイフンではない
説明がある	空ではなく、1～1024 文字
説明に WHAT がある	機能を説明している
説明に WHEN がある	トリガーとなるフレーズを含んでいる
説明にキーワードがある	分野固有の用語を含んでいる
XML タグがない	< または > の文字を含まない
任意フィールドが有効	license、compatibility（500 文字未満）、metadata

ステップ 4：トリガーの分析

有効化の精度という観点から説明を評価します：

トリガー不足のリスク：

• 汎用的すぎる（「プロジェクトを支援します」）
• よくある言い換えが不足している
• 分野のキーワードがない
• ファイル形式への言及がない（関連する場合）

過剰トリガーのリスク：

• 範囲が広すぎる（「ドキュメントを処理します」）
• Claude の組み込み機能と重複している
• 判別のための除外トリガーがない

テストクエリを生成します：

• スキルを起動すべきクエリを 5 件
• 起動すべきでないクエリを 5 件
• 境界事例（曖昧なクエリ）を 3 件

ステップ 5：指示の品質

評価基準	スコア（0～10）
具体性	指示は実行可能か（「適切に検証する」などの曖昧な表現ではないか）
完全性	すべてのワークフローが網羅されているか
エラー処理	よくある失敗に対処しているか
例	具体例が示されているか
段階的な情報開示	詳細なドキュメントが SKILL.md ではなく references/ にあるか
長さ	500 行／5000 トークン未満か
相互参照	references/scripts へのリンクが明確か

ステップ 6：アーキテクチャのレビュー（複数スキル）

サブスキルがある場合：

• メインスキルに明確なルーティングテーブルがある
• サブスキルの担当範囲が明確である
• 相互参照が有効である（ファイルが存在する）
• 命名が parent-child の規則に従っている
• 共有リファレンスが重複せず親にまとめられている
• エージェントの役割が明確である（Tier 4 の場合）

ステップ 7：スクリプトの品質（該当する場合）

• 目的、入力、出力を説明する docstring がある
• CLI インターフェースがある（argparse など）
• 構造化された出力（JSON）がある
• エラー処理がある（明確なメッセージを伴う try/except）
• ハードコードされたパスやシークレットがない
• 依存関係が最小限である

ステップ 8：スキルの健全性スコアを生成

採点方法（0～100）：

カテゴリ	配点	チェック項目
フロントマターの品質	25%	名前、説明、形式
トリガーの精度	20%	WHAT + WHEN + キーワード
指示の品質	25%	具体性、完全性、例
構造への準拠	15%	ファイル名、構成、リファレンス
スクリプトの品質	10%	該当する場合（スクリプトが不要なら満点）
段階的な情報開示	5%	3 段階システムの適切な使用

ステップ 9：トリガー評価セットを生成する

レビュー後、継続的なテスト用に構造化されたトリガー評価セットを生成します。

1. python scripts/generate_eval_set.py <path> を実行して、スターターセットを自動生成します
2. 生成されたクエリをレビューし、調整します：
   • 異なる言い回しやエッジケースを網羅する、トリガーすべきクエリを 8～10 件用意します
   • 明らかに無関係なものではなく、惜しいクエリをトリガーすべきでないクエリとして 8～10 件用意します
   • トリガーすべきクエリのセットには、くだけた話し言葉、タイプミス、あまり一般的でないドメインでの用法を含めます
3. 評価セットをスキルディレクトリの evals/evals.json に保存します

良いクエリは、現実的で具体的です（ファイルパス、コンテキスト、ドメインの詳細を含みます）。 悪いクエリは、抽象的すぎるもの（「このデータを整形して」）や、明らかに無関係なものです。

4. python scripts/optimize_description.py <path> --eval-set evals/evals.json を実行して、現在の説明を評価し、改善案を取得します
5. 完全な機能評価を行うために、/skill-forge eval <path> の実行を推奨します

ステップ 10：レポートを生成する

# Skill Review: [name]

## Health Score: [X]/100

## Summary
[2-3 sentence assessment]

## Scores by Category
| Category | Score | Notes |
|----------|-------|-------|
| Frontmatter | X/25 | [issues] |
| Triggering | X/20 | [issues] |
| Instructions | X/25 | [issues] |
| Structure | X/15 | [issues] |
| Scripts | X/10 | [issues] |
| Disclosure | X/5 | [issues] |

## Critical Issues (fix immediately)
- [issue 1]
- [issue 2]

## High Priority (fix within 1 week)
- [issue 1]

## Recommendations
- [suggestion 1]
- [suggestion 2]

## Suggested Test Queries
### Should Trigger
1. [query]
2. [query]
3. [query]

### Should NOT Trigger
1. [query]
2. [query]
3. [query]