スキルフォージ・進化

スキルの進化と改善

プロセス

ステップ1：問題の診断

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

カテゴリA：トリガー問題

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

カテゴリB：実行問題

• 不完全なワークフロー：スキルが途中で停止する
• 誤った出力：結果が期待と一致しない
• エラーハンドリングの欠如：障害が適切に処理されない
• パフォーマンス：遅すぎる、またはトークン消費が多い

カテゴリC：アーキテクチャ問題

• 機能不足：新しいユースケースがカバーされていない
• 規模の問題：スキルが大きすぎて分割が必要
• 相互参照問題：存在しないファイルへのリンク

カテゴリD：品質問題

• 結果の一貫性なし：同じ入力に対して異なる出力が返る
• 曖昧な指示：Claudeが毎回異なる解釈をする
• 具体例の不足：明確なガイダンスがない

ステップ2：カテゴリ別に修正を適用

修正：トリガー不足

1. 現在の説明文を読む
2. 不足しているトリガーフレーズを特定する
3. ドメインキーワードと言い換えを追加する
4. 関連するファイルタイプの言及を追加する
5. 今度はトリガーされるべき5つのクエリでテストする

よくある原因：

• 説明文が汎用的すぎる
• 一般的な言い換えが不足している
• 専門用語ばかりで平易な表現がない

修正テンプレート：

# 修正前（トリガー不足）
description: コード品質を分析します

# 修正後（具体的なトリガー）
description: >
  静的コード分析と品質評価。コードスタイル、複雑性、セキュリティ脆弱性、
  テストカバレッジをチェックします。ユーザーが「コードレビュー」「コード品質」
  「lint」「静的解析」「コードスメル」「コード監査」「コードをチェックして」
  と言ったときに使用します。

修正：過剰トリガー

1. 現在の説明文を読む
2. 無関係なクエリがトリガーされる理由を特定する
3. 否定トリガーを追加する（「〜には使用しないでください」）
4. 説明文をより具体的にする
5. トリガーされるべきでない5つのクエリでテストする

修正テンプレート：

# 修正前（過剰トリガー）
description: レビュー用に文書を処理します

# 修正後（具体的＋否定トリガー）
description: >
  PDFの法的文書を処理し、契約条項の抽出とコンプライアンスレビューを行います。
  法的契約書、NDA、利用規約に使用します。一般的な文書編集、フォーマット変更、
  非法律系のPDFには使用しないでください。

修正：実行問題

1. ワークフロー内の失敗ステップを特定する
2. ステップ間に明示的なバリデーションゲートを追加する
3. 明確な回復手順を含むエラーハンドリングを追加する
4. 「Xが失敗した場合はY」のフォールバックパスを追加する
5. 脆弱な操作にはスクリプトの導入を検討する

修正：品質問題

1. 曖昧な指示を具体的なものに置き換える
2. 期待される入力/出力の具体例を追加する
3. 「こうする、こうしない」比較を明示的に追加する
4. 最終出力の前に品質チェックステップを追加する
5. バリデーションスクリプトの導入を検討する

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

構造化ワークスペースを使用して、反復全体の改善を追跡します。

eval-workspace/
  iteration-1/          # 初回バージョン
    eval-0/with_skill/  # 評価結果
    eval-0/baseline/
    benchmark.json      # 集計メトリクス
    benchmark.md        # 人間が読めるレポート
    feedback.json       # ユーザーフィードバック
  iteration-2/          # 最初の改善後
    eval-0/with_skill/
    eval-0/baseline/
    benchmark.json
    benchmark.md
    feedback.json

反復ループ：

1. 修正をスキルに適用する
2. /skill-forge eval <path> を iteration-<N+1>/ に実行する
3. /skill-forge benchmark <path> を --previous iteration-<N>/ で実行する
4. ベンチマーク比較でリグレッションを確認する
5. ユーザーフィードバックを feedback.json に収集する
6. フィードバックを読み、反復する（ステップ2に戻る）

反復を停止するタイミング：

• ユーザーが満足したと言ったとき
• すべてのフィードバックが空（すべて良好）のとき
• ベンチマークが反復間で有意な進歩を示さないとき
• パス率が定義されたしきい値を満たしたとき

ステップ3b：自己修復ループ

完全な評価パイプラインを使わない迅速な修正用：

1. 修正を適用する
2. 元の失敗ケースでテストする
3. 他の3つのケースでテストする（リグレッションチェック）
4. 修正が成功した場合：
   -> ディレクティブ/SKILL.mdを更新する
   -> 学んだことをreferencesまたはSKILL.mdに文書化する
5. 修正が失敗した場合：
   -> 理由を診断する
   -> 代替アプローチを試す
   -> 繰り返す

ステップ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：アーキテクチャの進化

スキルがその階層を超えた場合：

Tier 1 → Tier 2（スクリプトが必要）：

1. 脆弱/決定論的な操作を特定する
2. scripts/ にスクリプトを作成する
3. SKILL.mdを更新してスクリプトを参照する
4. スクリプトを独立してテストする

Tier 2 → Tier 3（サブスキルが必要）：

1. 分離可能な個別のワークフローを特定する
2. それぞれを独自の skills/{parent}-{child}/SKILL.md に抽出する
3. ルーティングテーブルでメインのSKILL.mdを更新する
4. 共有知識を references/ に移動する
5. install.shを更新する

Tier 3 → Tier 4（エージェントが必要）：

1. 並列実行可能なワークフローを特定する
2. agents/ にエージェント定義を作成する
3. audit/full-analysisサブスキルを更新してエージェントに委譲する
4. 並列実行をテストする

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

進化後：

1. フロントマターの metadata.version を更新する（存在する場合）
2. SKILL.mdまたはリファレンスファイルに学びを追加する
3. 影響を受けるすべての相互参照を更新する
4. バリデーションを再実行：python scripts/validate_skill.py <path>
5. ワークフロー全体をエンドツーエンドでテストする

一般的な進化パターン

パターン：業種検出の追加

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

## 業種検出

コンテキストからユーザータイプを検出します：
- **タイプA**: [シグナル] → [動作]
- **タイプB**: [シグナル] → [動作]

パターン：品質ゲートの追加

出力品質に一貫性がない場合：

## 品質ゲート

出力を提供する前に：
- [ ] [チェック1]
- [ ] [チェック2]
- [ ] [チェック3]

パターン：スコアリングの追加

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

## スコアリング（0-100）

| カテゴリ | 重み |
|----------|------|
| カテゴリA | 30% |
| カテゴリB | 30% |
| カテゴリC | 20% |
| カテゴリD | 20% |