---
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)は以下を指定:

```yaml
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