skill-forge-evolve

スキルの進化と改善

プロセス

ステップ 1：問題を診断する

ユーザーに質問するか、ログを分析して問題のカテゴリを特定します。

カテゴリ A：トリガーに関する問題

• トリガー不足：起動すべきときにスキルが起動しない
• 過剰トリガー：起動すべきでないときにスキルが起動する
• 誤トリガー：誤ったサブスキルが起動する

カテゴリ B：実行に関する問題

• ワークフローが不完全：スキルが完了前に停止する
• 出力が不正確：結果が期待と一致しない
• エラー処理の不足：失敗に適切に対処できない
• パフォーマンス：処理が遅すぎる、または使用トークン数が多すぎる

カテゴリ C：アーキテクチャに関する問題

• 機能の不足：新しいユースケースに対応していない
• 規模の問題：スキルが大きすぎるため、分割が必要
• 相互参照の問題：存在しないファイルへのリンクがある

カテゴリ D：品質に関する問題

• 結果に一貫性がない：同じ入力でも出力が異なる
• 指示が曖昧：Claude が毎回異なる解釈をする
• 例が不足：具体的なガイダンスがない

ステップ 2：カテゴリに応じて修正する

修正：トリガー不足

1. 現在の説明を読む
2. 不足しているトリガーフレーズを特定する
3. ドメインのキーワードや言い換えを追加する
4. 関連する場合はファイル形式にも言及する
5. 新たに起動するはずのクエリを 5 件使ってテストする

一般的な原因：

• 説明が一般的すぎる
• よく使われる言い換えが不足している
• 平易な言葉を使わず、専門用語だけを使っている

修正テンプレート：

# Before (under-triggers)
description: Analyzes code quality

# After (specific triggers)
description: >
  Static code analysis and quality assessment. Checks code style,
  complexity, security vulnerabilities, and test coverage. Use when
  user says "code review", "code quality", "lint", "static analysis",
  "code smell", "code audit", or "check my code".

修正：過剰トリガー

1. 現在の説明を読む
2. 関連のないクエリで起動する理由を特定する
3. 否定的なトリガー（「次の場合は使用しない」など）を追加する
4. 説明をより具体的にする
5. 起動しないはずのクエリを 5 件使ってテストする

修正テンプレート：

# Before (over-triggers)
description: Processes documents for review

# After (specific + negative triggers)
description: >
  Processes PDF legal documents for contract clause extraction and
  compliance review. Use for legal contracts, NDAs, terms of service.
  Do NOT use for general document editing, formatting, or non-legal PDFs.

修正：実行に関する問題

1. ワークフロー内で失敗しているステップを特定する
2. ステップ間に明示的な検証ゲートを追加する
3. 明確な復旧手順を伴うエラー処理を追加する
4. 「X に失敗した場合は Y を行う」という代替経路を追加する
5. 不安定な処理にはスクリプトの追加を検討する

修正：品質に関する問題

1. 曖昧な指示を具体的な指示に置き換える
2. 期待される入力と出力の具体例を追加する
3. 「こちらを行い、あちらは行わない」という比較を明示する
4. 最終出力の前に品質チェックの手順を追加する
5. 検証スクリプトの追加を検討する

ステップ 3：反復作業用ワークスペースのプロトコル

構造化されたワークスペースを使用して、反復作業における改善を追跡します。

eval-workspace/
  iteration-1/          # First version
    eval-0/with_skill/  # Eval results
    eval-0/baseline/
    benchmark.json      # Aggregated metrics
    benchmark.md        # Human-readable report
    feedback.json       # User feedback
  iteration-2/          # After first improvement
    eval-0/with_skill/
    eval-0/baseline/
    benchmark.json
    benchmark.md
    feedback.json

反復ループ：

1. スキルに修正を適用する
2. /skill-forge eval <path> を iteration-<N+1>/ に対して実行する
3. --previous iteration-<N>/ を指定して /skill-forge benchmark <path> を実行する
4. ベンチマークの比較結果を確認し、リグレッションがないか調べる
5. ユーザーからのフィードバックを feedback.json に集める
6. フィードバックを読み、反復する（ステップ 2 に戻る）

次の場合は反復を終了します：

• ユーザーが満足したと伝えた
• フィードバックがすべて空である（すべて問題なし）
• ベンチマークで反復間に意味のある進展が見られない
• 合格率が定義済みのしきい値を満たしている

ステップ 3b：自己調整ループ

評価パイプライン全体を実行せずに、すばやく修正する場合に使用します。

1. Apply the fix
2. Test with the original failing case
3. Test with 3 other cases (regression check)
4. If fix works:
   -> Update the directive/SKILL.md
   -> Document the learning in references or SKILL.md
5. If fix fails:
   -> Diagnose why
   -> Try alternative approach
   -> Repeat

ステップ 3c：説明の最適化ループ

トリガーに関する問題（カテゴリ A）には、自動最適化ループを使用します。

1. トリガー評価セットを生成する：python scripts/generate_eval_set.py <path>
2. ユーザーと一緒に評価セットを確認し、調整する
3. 最適化を実行する：python scripts/optimize_description.py <path> --eval-set evals.json
4. 学習／テスト分割のスコアと改善案を確認する
5. 提案された説明の変更を適用する
6. 最適化を再実行し、改善度を測定する
7. テストスコアが最も高い説明を選ぶ（学習スコアではなく、過学習を防ぐため）
8. 最大 5 回、またはテストスコアが頭打ちになるまで反復する

ステップ 4：アーキテクチャの進化

スキルが現在のティアでは対応しきれなくなった場合：

ティア 1 -> ティア 2（スクリプトが必要）：

1. 壊れやすい／決定論的な処理を特定します
2. scripts/ にスクリプトを作成します
3. SKILL.md を更新してスクリプトを参照します
4. スクリプトを単独でテストします

ティア 2 -> ティア 3（サブスキルが必要）：

1. 切り分け可能な個別のワークフローを特定します
2. それぞれを独自の skills/{parent}-{child}/SKILL.md に抽出します
3. メインの SKILL.md を更新し、ルーティングテーブルを追加します
4. 共通のナレッジを references/ に移動します
5. install.sh を更新します

ティア 3 -> ティア 4（エージェントが必要）：

1. 並列で実行できるワークフローを特定します
2. agents/ にエージェント定義を作成します
3. 監査／詳細分析サブスキルを更新し、エージェントに処理を委任します
4. 並列実行をテストします

ステップ 5：バージョン管理

進化の後：

1. フロントマターの metadata.version を更新します（存在する場合）
2. 学びを SKILL.md または参照ファイルに追加します
3. 影響を受ける相互参照を更新します
4. 検証を再実行します：python scripts/validate_skill.py <path>
5. ワークフロー全体を最初から最後までテストします

よくある進化パターン

パターン：業界の検出を追加する

ユーザーのタイプに応じてスキルの動作を適応させる必要がある場合：

## Industry Detection
Detect user type from context:
- **Type A**: [signals] -> [behavior]
- **Type B**: [signals] -> [behavior]

パターン：品質ゲートを追加する

出力品質にばらつきがある場合：

## Quality Gates
Before delivering output:
- [ ] [Check 1]
- [ ] [Check 2]
- [ ] [Check 3]

パターン：スコアリングを追加する

ユーザーが測定可能な出力を必要とする場合：

## Scoring (0-100)
| Category | Weight |
|----------|--------|
| Category A | 30% |
| Category B | 30% |
| Category C | 20% |
| Category D | 20% |