スキルレビューとバリデーション
プロセス
ステップ 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: スクリプト品質（存在する場合）
- 目的、入力、出力を含むドキュメント文字列がある
- CLIインターフェース（argparse または同等のもの）
- 構造化出力（JSON）
- エラーハンドリング（try/except と明確なメッセージ）
- ハードコードされたパスやシークレットがない
- 最小限の依存関係
ステップ 8: スキル健康スコアの生成
採点方法（0～100点）:
| カテゴリ | 重み | チェック項目 |
|---|---|---|
| フロントマター品質 | 25% | 名前、説明、形式 |
| トリガー精度 | 20% | WHAT + WHEN + キーワード |
| 命令文品質 | 25% | 具体性、完全性、例 |
| 構造準拠 | 15% | ファイル命名、構成、参照 |
| スクリプト品質 | 10% | 該当する場合（スクリプト不要の場合は満点） |
| 段階的開示 | 5% | 3レベルシステムの適切な使用 |
ステップ 9: トリガー評価セットの生成
レビュー後、継続的なテストのための構造化トリガー評価セットを生成:
python scripts/generate_eval_set.py <path>を実行してスターターセットを自動生成- 生成されたクエリをレビューおよび調整:
- 8～10のトリガーすべきクエリが、異なる言い回しやエッジケースをカバーしていることを確認
- 8～10のトリガーすべきでないクエリはニアミス（明らかに無関係ではない）であることを確認
- トリガーすべきセットには、日常会話、タイプミス、珍しいドメイン使用法を含める
- 評価セットをスキルディレクトリの
evals/evals.jsonに保存
良いクエリ は現実的で具体的（ファイルパス、コンテキスト、ドメインの詳細を含む）です。 悪いクエリ は汎用的すぎる（「このデータをフォーマットして」）か、明らかに無関係です。
python scripts/optimize_description.py <path> --eval-set evals/evals.jsonを実行して現在の説明文をスコアリングし、改善提案を取得/skill-forge eval <path>を実行して完全な機能評価を推奨
ステップ 10: レポートの生成
# スキルレビュー: [name]
## 健康スコア: [X]/100
## 概要
[2～3文の評価]
## カテゴリ別スコア
| カテゴリ | スコア | 備考 |
|----------|-------|-------|
| フロントマター | X/25 | [問題点] |
| トリガー | X/20 | [問題点] |
| 命令文 | X/25 | [問題点] |
| 構造 | X/15 | [問題点] |
| スクリプト | X/10 | [問題点] |
| 開示 | X/5 | [問題点] |
## 重大な問題（即時修正）
- [問題 1]
- [問題 2]
## 優先度の高い問題（1週間以内に修正）
- [問題 1]
## 推奨事項
- [提案 1]
- [提案 2]
## 推奨テストクエリ
### トリガーすべき
1. [クエリ]
2. [クエリ]
3. [クエリ]
### トリガーすべきでない
1. [クエリ]
2. [クエリ]
3. [クエリ]