Skill Evolve

---

name: skill-evolve description: "既存スキル(SKILL.md / プロンプト / マニュアル)を SkillOpt 方式で進化させる汎用メタスキル。pilot で feedback function を実証 → 並列ミニバッチで試走・リフレクション → 提案統合 → minibatch ゲート → held-out validation → 改善のみ採用、というループを subagent で回す。学習率(edit_budget)と2層棄却バッファ(per-run + permanent)で暴走と長期失敗反復を防ぐ。Use when user says 'スキル最適化', 'skill optimize', 'プロンプト最適化', 'skill-evolve'." context: fork model: sonnet allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent

Instructions

任意の SKILL.md(あるいはプロンプト/マニュアル)を対象に最適化ループを回す 汎用メタスキル。

本ファイルがワークフロー仕様の単一情報源。関連文書の分担:

| 文書 | 内容 | |---|---| | README.md | 背景・キーアイデア・いつ使うか・位置づけ(概念のみ) | | USAGE.md | 人間が担う実務手順(Phase A〜D)と運用ノウハウ | | references/contracts.md | 選手 / リフレクタ / コーチの subagent 起動契約(実行時に Read する) | | references/formats.md | 全データフォーマット(編集案・棄却バッファ・test_cases・config) | | references/red-flags.md | 実行中に出てくる「合理化」の全パターン表 |

役割分離の原則:選手(対象スキルで試走)・リフレクタ(診断)・コーチ(編集案)を 3 subagent に分ける。同一 subagent に役割を兼ねさせない(自己評価バイアスの構造的回避)。

---

いつ使うか

• 頻繁に使われる対象スキルを堅牢化したいとき
• 偽陽性 / 偽陰性が増えてきて再チューニングしたいとき
• モデル切替(例: sonnet → opus 等)で挙動が変わったとき

使わない場面:

• 1 回限りのアドホックなプロンプト改善(評価コストが割に合わない)
• rubric が立てられないタスク(採点不能のため自動最適化は機能しない)
• orchestrator スキル(単体 SKILL 最適化とは別問題)

詳細な位置づけや適用範囲は README.md を参照。

---

パス規約(全ステップ共通)

全状態は対象プロジェクト直下の .claude/skill-evolve/ に集約する。対象スキルのディレクトリには一切ファイルを置かない(SKILL.md 1 枚のままクリーンに保つ)。

<project>/.claude/skill-evolve/
├── config.yaml                        ← プロジェクト共通デフォルト
├── shared/                            ← スキル横断で共有する permanent buffer(symlink 不使用)
│   └── <domain>.yaml
└── targets/<skill-name>/
    ├── config.yaml                    ← この対象の設定(共通デフォルトを上書き)
    ├── assets/                        ← 恒久資産(git 管理、削除厳禁)
    │   ├── baseline.md                ← 起点バックアップ
    │   ├── changelog.md               ← 全 run 累積の採用編集 + メトリクス推移
    │   ├── rejection-buffer-permanent.yaml  ← 恒久的失敗パターン + structural_defects
    │   ├── feedback_spec.md           ← Step -1 で確定した μ_f 仕様
    │   ├── coach_meta_prompt.md       ← ドメイン前提のみ(下記「二重管理の禁止」参照)
    │   └── pilot_report.md            ← Step -1 の人間判断との一致度
    ├── tests/
    │   ├── test_cases.md              ← テストケース(形式は references/formats.md)
    │   └── fixtures/case-XX/          ← ケースごとの入力データ
    └── runs/<YYYY-MM-DD-N>/           ← run ごとの使い捨てデータ(gitignore 対象)
        ├── rejection-buffer-run.yaml  ← この run の却下案
        └── iter-<N>/                  ← per-iteration 作業ディレクトリ
            └── structural_themes_for_promotion.yaml

• このレイアウトは scripts/skill-evolve init <skill-name> が生成する(人間の手順は USAGE.md Phase A)
• runs/ 配下だけが gitignore 対象。assets/ と tests/ は git 管理し「育つ知識ベース」として残す
• 以降、<target> = .claude/skill-evolve/targets/<skill-name> と表記する

二重管理の禁止: coach_instruction(コーチへの恒久禁止ルール)の単一情報源は rejection-buffer-permanent.yaml である。コーチ起動契約で毎回全文を渡すため、 coach_meta_prompt.md への転記は 行わない。coach_meta_prompt.md には ドメイン前提とプロジェクト固有の禁止事項だけを書く。

---

入力契約

呼び出し時、ユーザー(または上位 skill)は以下を指定:

target: <対象スキル名>    # .claude/skill-evolve/targets/<name>/ が存在すること
# 以下は config.yaml の値を上書きしたい場合のみ指定
pilot_mode: full | minimal
max_iterations: 3
edit_budget: 4               # 学習率。アブレーションでの最適値
acceptance_margin: 5         # validation 改善がこのポイント以上で採用
n_minibatches: 4

パラメータの解決順: 呼び出し時指定 > <target>/config.yaml > .claude/skill-evolve/config.yaml。 改善対象のパスは <target>/config.yaml の skill_path から読む(config 形式は references/formats.md)。

pilot_mode のプリセット

| pilot_mode | test_cases | max_iter | n_minibatches | 立ち上げ目安 | 想定用途 | |---|---|---|---|---|---| | full | 12 (train 8 / val 4) | 3 | 4 | 3〜5 時間 | 本格運用 | | minimal | 6 (train 4 / val 2) | 2 | 2 | 1〜2 時間 | 触ってみる / 効きそうか確認 |

minimal モードでも permanent buffer は通常通り更新する(後で full モードに移行した ときに学びが引き継げる)。minimal で見えた手応えを根拠に full への投資判断ができる。

test_cases は <target>/tests/test_cases.md に置く。[critical] を最低 1 つ含めること。 形式・ケース数の詳細は references/formats.md の「test_cases.md」節を参照。

---

ワークフロー

Step -1: pilot run + feedback function 設計(必須、最重要)

自動最適化の品質は採点ロジック(feedback function μ_f)の精度で決まる。pilot を飛ばして本ループに入ると、誤った勾配でスキルが歪んでいく。

実施手順:

1. test_cases から 5〜10 ケース をピックアップ
2. 対象 SKILL を手動で適用(/<対象skill名> で実行 or Agent tool で dispatch)
3. rubric で採点
4. 採点結果が人間の直感と一致するか確認
   • 直感的に正解と思ったケースが × → 採点ロジックが間違い、rubric を修正
   • 直感的に明らかな失敗が ○ → 採点が甘い、[critical] を厳しくする
5. コーチへの初期メタプロンプトを下書き(coach_meta_prompt.md)
6. 1〜2 イテレーションだけ手動でループを回し、提案された編集案を人間が読んで妥当性確認
7. コスト試算: 1イテレーション当たりの LLM 呼び出し数 × 単価 × 想定イテレーション

成果物(いずれも <target>/assets/ に保存):

• feedback_spec.md — μ_f の仕様(入力、出力、評価基準、[critical] の判定根拠)
• coach_meta_prompt.md — コーチへの初期指示(ドメイン前提のみ)
• pilot_report.md — 数値結果 + 人間判断との一致度評価

Step 0: 静的整合チェックと準備

0a. description ↔ body 整合チェック

frontmatter description が謳う trigger / 用途と、body がカバーする範囲に乖離がないか確認。乖離があれば本ループに入る前に人間が修正(コーチが description に合わせて body を「再解釈」する false positive を防ぐ)。

0b. 準備

1. パラメータを解決し(入力契約の解決順)、<target>/config.yaml の skill_path を Read して current_skill に保持
2. <target>/assets/baseline.md が存在することを確認(無ければ init 未実施。中断して USAGE.md Phase A へ誘導)
3. run ディレクトリを作成: <target>/runs/<YYYY-MM-DD-N>/(N は同日内の連番)。 その直下に空の rejection-buffer-run.yaml を作成(per-run buffer は run ごとに新規)
4. <target>/config.yaml の shared_permanent_buffers に列挙された .claude/skill-evolve/shared/*.yaml を確認。コーチに渡す permanent buffer は target 自身の assets/rejection-buffer-permanent.yaml と shared 分を連結 したもの
5. 改善対象スキルのディレクトリには何も書き込まない

Step 1: 並列ミニバッチ rollout

train ケースを n_minibatches 個に均等分割し、各ミニバッチを 独立した選手 subagent で並列 dispatch(単一メッセージ内で複数 Agent 呼び出し)。同 subagent は再利用しない。

回収する情報(完全トレース):

| 種類 | 取り方 | |---|---| | 最終成果物 | subagent レポート | | tool_uses (execution trace) | Agent tool 戻り値 usage.tool_uses | | tool_outputs (evaluation trace) | subagent レポート内の「ツール戻り値要約」節 | | reasoning(自己申告) | レポート「推論メモ」節 | | 不明瞭点・裁量補完 | レポート末尾 |

選手 subagent のプロンプトは references/contracts.md の「選手 subagent 起動契約」を使う。

「成功 / 失敗の ○×」ではなく 自然言語の所見 を残すのが本手法の核心。情報量が桁違いに多い。

Step 2: ミニバッチ単位リフレクション(並列)

各ミニバッチごとに 新規のリフレクタ subagent を独立 dispatch(起動契約は references/contracts.md)。コーチとは役割を分離する。

リフレクタが出力するもの(全項目必須、YAML 形式は起動契約に定義):

• 失敗パターン仮説(case ごとに 1〜2 行)
• rubric 判定文言マッピング: 落ちた rubric 項目について feedback_spec.md の判定文言を 引用付き で明示
• 失敗テーマ ID 割り振り: 複数 case に共通する失敗を 1 テーマとしてラベリング
• 構造欠陥ラベル: 各テーマに structure_defect_label: local | structural を付与
  • local: 局所修正(add / delete / replace)で対処可能
  • structural: 構造再編成が必要。コーチは手を出さず、Step 9 で permanent buffer へ即時昇格
• 共通原因 / 未充足な前提 / 削除候補 / tool_uses 偏り観察

精度のみで判断するとスキルの構造的欠陥が隠れる。質的シグナルを常に主、メトリクスは補助。

Step 3: 提案統合 → 学習率まで圧縮

新規のコーチ subagent を references/contracts.md の「コーチ subagent 起動契約」で dispatch。渡すもの:

• current_skill 全文 / feedback_spec.md 全文 / coach_meta_prompt.md 全文
• 全ミニバッチのリフレクション(themes と structure_defect_label 込み)
• per-run buffer(runs/<run-id>/rejection-buffer-run.yaml)
• permanent buffer(target 分 + shared 分を連結。coach_instruction 絶対遵守)
• edit_budget 上限

コーチの統合手順(詳細は起動契約に記載):

1. structural テーマはコーチが触らず runs/<run-id>/iter-<N>/structural_themes_for_promotion.yaml に分離
2. local テーマについてのみ編集案を生成(op は add / delete / replace の 3 種のみ)
3. 重複マージ → theme 単位バンドル → 優先順位付け → edit_budget 件まで truncate
4. 提出前に自己診断チェック(起動契約に列挙)を全件通す

編集案フォーマット(rubric_mapping 文字列一致・waves_pattern・delete_considered・bloat_check の 必須ルール込み)は references/formats.md の「編集案」節に定義。 rubric_mapping が空、または引用が feedback_spec.md の判定文言と文字列一致しない編集案は提出禁止。

Step 4: minibatch ゲート(改善検証)

サンプル効率の核心。各編集案ごとに:

1. current_skill をベースに編集を仮適用したパッチ案を作る(runs/<run-id>/iter-<N>/ 配下、対象スキル本体は触らない)
2. 同じミニバッチ群 で σ(編集前)と σ'(編集後)を測定
3. σ' > σ → Step 5 へ
4. σ' ≤ σ → 即却下、rejection-buffer-run.yaml 追記

validation を消費する前にここで篩い落とす。

Step 5: held-out validation 評価

Step 4 通過案だけ:

1. validation ケース全てに対して新規の検証 subagent で試走
2. val_score_after_<i> を記録
3. 同じく current_skill(編集前)で validation 試走、val_score_before を記録(毎イテレーション取り直す)

Step 6: 採否判定 と 適用

各通過案について:

• delta_i = val_score_after_<i> - val_score_before
• delta_i >= acceptance_margin なら採用候補
• 採用候補が複数なら delta_i 最大の 1 件のみ採用(1 イテレーション 1 編集)
• 採用 → skill_path に書き戻し、<target>/assets/changelog.md に run-id 付きで追記
• 不採用 → rejection-buffer-run.yaml に追記(フォーマットは references/formats.md)

Step 7: 終了判定

次のいずれかで停止:

• max_iterations 到達
• 連続 2 イテレーションで採用ゼロ(頭打ち)
• 連続 2 ロールバック(構造的に自動改善が機能していない → スキル設計を疑う)

停止時にサマリー出力:

• baseline からの累積 train / validation スコア差分
• 採用 / 試行編集の総数
• ミニバッチ別の提案採用率
• 主要却下パターン(rejection-buffer-run から 3 つ)

Step 8: 安全装置(各イテレーション開始時に横断作動)

• 各イテレーション開始時、assets/baseline.md との validation スコア差をチェック。baseline を下回ったら直前の編集をロールバック
• edit_budget を超える編集案は rationale の強さで truncate
• skill_path の上書きは Step 6 の採用確定時のみ。仮適用は runs/ 配下の別ファイル

Step 9: 棄却バッファの 2 層運用と昇格(ループ停止後に 1 回)

run 終了時、rejection-buffer-run.yaml から assets/rejection-buffer-permanent.yaml への昇格判定:

| 昇格条件 | 内容 | |---|---| | 頻度 | 過去の run を通じて、類似編集案が 3 回以上却下された(scripts/skill-evolve promote が候補を横断抽出する) | | 失敗モードの明確さ | failure_mode_hypothesis が一般化可能(名前付きパターン) |

昇格時、類似案を クラスタリングして代表案 1 件 で記録(肥大化防止)。 昇格の最終判断は人間が行う(USAGE.md Phase D-3)。自動昇格はしない。

昇格先の選択: そのパターンが対象スキル固有なら assets/rejection-buffer-permanent.yaml、 同ドメインの複数スキルに共通なら .claude/skill-evolve/shared/<domain>.yaml に記録し、 各 target の config.yaml の shared_permanent_buffers に登録する。

構造欠陥テーマの即時昇格(per-run buffer を経由しない)

リフレクタが Step 2 で structure_defect_label: structural と診断したテーマは、 通常の昇格条件を満たさなくても 即時に permanent buffer へ昇格 する。

理由: structural と診断されたテーマは局所修正では対処不能。コーチが何度試しても 採用されないため、最初から「コーチは触らない」と固定するのが安全。

処理:

1. コーチが Step 3 で runs/<run-id>/iter-<N>/structural_themes_for_promotion.yaml に分離した theme を読む
2. assets/rejection-buffer-permanent.yaml の structural_defects セクションに追記
3. 次イテレーション以降、コーチはこのテーマを無視する(buffer 経由で自動的に伝わる。 coach_meta_prompt.md への転記は不要 — パス規約の「二重管理の禁止」参照)

これは 手動チューニングに戻るシグナル。structural_defects が 3 件以上溜まったら、 本ループを継続する前に手動で構造再編成を行うのが筋。

buffer の YAML フォーマット(promoted_patterns / structural_defects)は references/formats.md に定義。 coach_instruction フィールドはコーチが毎回読んで 絶対遵守 する恒久ルール。

---

実行後に更新されるファイル

| ファイル | 更新タイミング | 寿命 | |---|---|---| | <skill_path>(対象スキル本体) | Step 6 採用確定時のみ | — | | <target>/assets/changelog.md | Step 6(採用ごと) | 恒久(git 管理) | | <target>/assets/rejection-buffer-permanent.yaml | Step 9(人間承認後) | 恒久(削除厳禁) | | <target>/runs/<run-id>/rejection-buffer-run.yaml | Step 4 / 6(却下ごと) | run 限り(gitignore) | | <target>/runs/<run-id>/iter-<N>/ | Step 3 / 4(作業ファイル) | run 限り(gitignore) |

assets/rejection-buffer-permanent.yaml と assets/coach_meta_prompt.md は 長期資産。削除や軽率なリセットは禁止。

---

Red flags(本ループ実行中の自戒)

主要 3 件のみ(全パターン表は references/red-flags.md):

• pilot を飛ばそう → μ_f が壊れていると後段は全部無駄。飛ばし禁止
• 役割兼任で速くしよう → 自己評価バイアスが入る。選手 / リフレクタ / コーチは必ず別 subagent
• validation も train と同じケースで → 過学習一直線。完全分離必須

---

関連

• subagent 起動契約(選手 / リフレクタ / コーチ): references/contracts.md
• データフォーマット(編集案 / バッファ / test_cases / config): references/formats.md
• Red flags 全パターン表: references/red-flags.md
• 実行例テンプレート: examples/pilot-template.md
• コーチへのメタプロンプト雛形: examples/coach_meta_prompt_template.md
• 人間の実務手順とトラブルシューティング: USAGE.md