skill-optimizer

スキルオプティマイザー

自己進化型のスキル最適化です。SKILL.md を、凍結されたエージェントの学習可能なパラメーターとして扱います。検証によるゲート、予算上限、アトミックなバージョン管理を備えています。

SkillOpt（arXiv 2605.23904、Microsoft Research、2026年5月）に基づいています。

このスキルを呼び出すタイミング

ユーザーが次のことを望んでいる場合に使用します。

• ベンチマークに対する既存スキルの実行品質を改善する
• 新しいスキル用のベンチマークファイルを作成する
• 対象モデルを切り替えた後にスキルを再調整する

絶対厳守のルール

• 検証によるゲートは必須です。 SKILL.md を書き換える前に、すべての候補が sel-set に対して中央値3回の評価を行い、epsilon=0.05 のマージンをクリアする必要があります。
• フロントマターの変更は禁止です。 オプティマイザーが編集するのは本文のみです。ルーティングサーフェス（triggers:、brain_first:）は変更しません。
• 同梱スキルには、明示的なオプトインと独立したホールドアウトセットが必要です。 gbrain に同梱されたスキルを自動で変更することはできません。スキルをその場で書き換えるには、ユーザーが --allow-mutate-bundled と --held-out <path> の両方を指定し、ベンチマークと重複しないタスクを5件以上用意する必要があります。ホールドアウトセットがない場合、実行は拒否されます（終了コード 2）。代わりに、--allow-mutate-bundled を省略する（または既定値である dream-cycle フェーズの --no-mutate を指定する）と、レビュー用に proposed.md を出力できます。このレビュー専用出力にホールドアウトは不要です。
• ブートストラップ出力には人によるレビューが必要です。 --bootstrap-from-skill と --bootstrap-from-routing はどちらもセンチネルを書き込みます。生成された判定器をレビューして強化し、センチネルを削除したうえで、--bootstrap-reviewed を付けて再実行してから最適化でファイルを使用してください。

パイプライン

gbrain skillopt <skill-name> [flags]
  │
  ├── Pre-flight gates
  │     ├── working tree clean (or --force)
  │     ├── benchmark valid + D_sel >= 5 (D17)
  │     ├── cost preflight (D3) — refuses over --max-cost-usd
  │     └── per-skill DB lock (D14)
  │
  ├── Baseline eval on D_sel (sets best_sel_score)
  │
  ├── for epoch in 1..N:
  │     for step in 1..steps_per_epoch:
  │       ├── forward pass: rollouts on D_train batch
  │       ├── backward pass: reflect × 2 (failures + successes per D7)
  │       ├── rank + clip via LR cosine schedule
  │       ├── apply edits (body-only per D5, tagged result per D9)
  │       ├── validation gate: median-of-3 + epsilon=0.05 (D12)
  │       └── if accept: commit via D8 history-intent-first
  │     │
  │     └── slow update (D6) if no improvement this epoch
  │
  └── Final test eval on D_test → run receipt

スキルの保存場所

プラグインに同梱されたスキルは読み取り専用のスナップショットとして提供されるため、その隣にベンチマークや最適化成果物を書き込むことはできません。書き込み可能な独自のスキルディレクトリに対して skillopt を実行してください。--skills-dir <path> を渡すか（gbrain skillopt X --skills-dir ~/my-project/skills）、skills/ ツリーを含むワークスペースから実行すると、CLI が自動検出します。以下に示す skills/X/... の各パスはすべて、プラグインのスナップショットではなく、その書き込み可能なディレクトリ（自作のスキル、skillify で作成したスキル、または brain に格納されたスキルパック）を指します。

スキル自体からベンチマークを開始する（一般的なケース）

ユーザーがベンチマークを自分で作成することはありません。また、空のファイルから始めるべきでもありません。 ユーザーから「スキル X を改善して」と言われたときに、skills/X/skillopt-benchmark.jsonl が存在しない場合は、SKILL.md から直接スターターを生成します。

1. スターターを生成します。 次を実行します。

   gbrain skillopt X --bootstrap-from-skill
   

   1 回の LLM 呼び出しで skills/X/SKILL.md を読み取り、スキルが生成するものと「良い」状態を推測して、各タスクにルール判定を付けた約 15 個のタスクを skills/X/skillopt-benchmark.jsonl に書き込み、さらに # BOOTSTRAP_PENDING_REVIEW のセンチネルを追加します。routing-eval.jsonl は不要です。--bootstrap-tasks N で件数を調整できます（最大 50）。
2. 判定をレビューし、さらに強化します。 これはあなたの仕事であり、品質を左右します。生成されたルールチェックは弱い下書きです。モデルは汎用的な contains、緩い max_chars、または創作した見出しを出力しがちです。各タスクを読み、曖昧なチェックを修正し、スキルで実際に必要な必須項目（実在するセクション名、適切な文字数上限、ソースが想定される場合の min_citations、スキルが実際に使用するツールに対する tool_called／tool_not_called）を追加します。内容の薄いベンチマークは、品質の定義も薄いものに最適化します。安易に承認しないでください。
3. センチネル行（最後の行にある # BOOTSTRAP_PENDING_REVIEW）を削除します。
4. --split 1:1:1 を指定してオプティマイザーを実行します。

   gbrain skillopt X --bootstrap-reviewed --split 1:1:1
   

   15 個のタスクからなるスターターでは、1:1:1 の分割が必須です。デフォルトの 4:1:5 では、検証セットが floor(15/10)=1 となり、D_sel >= 5 の下限を下回るため、オプティマイザーは d_sel_too_small で処理を拒否します（4:1:5 には約 50 個のタスクが必要です）。費用を事前に確認するには、最初に --dry-run を追加します。

ベンチマーク行の形式（ジェネレーターが 1 行ずつ書き込みます）：

{"task_id":"x-001","task":"<user prompt>","judge":{"kind":"rule","checks":[{"op":"max_chars","arg":1800},{"op":"contains","arg":"agenda"}]}}

強化に使用するルールチェック用語：contains、regex、section_present、max_chars、min_citations、tool_called、tool_not_called。ルール判定は決定論的で無料ですが、品質が順序付け、プライバシー、拒否の境界、ファイル配置に左右されるスキルには浅すぎます。そのような場合は、レビュー時により充実したチェック（または llm 判定）を手動で追加してください。

代替方法 — 自分で作成する。 生成されたスターターの品質が低い場合（まれですが、行動の形が非常に重要なスキルでは起こり得ます）は破棄し、JSONL を自分で作成します。SKILL.md を読み、ありふれた中間ケースを網羅する現実的なタスクを約 15 個作成し、それぞれに 2 個以上のルールチェックを付けて、skills/X/skillopt-benchmark.jsonl に保存し、--split 1:1:1 を指定して実行します。詳しい手順は https://github.com/garrytan/gbrain/blob/master/docs/tutorials/improving-skills-with-skillopt.md にあります。

判断ツリー

状況	対応
スキルにベンチマークがない	gbrain skillopt foo --bootstrap-from-skill → 判定をレビューして強化 → センチネルを削除 → gbrain skillopt foo --bootstrap-reviewed --split 1:1:1（上記のセクションを参照）
スキルに routing-eval.jsonl があり、作業の出発点にしたい	gbrain skillopt foo --bootstrap-from-routing → 生成されたタスクをレビュー → --bootstrap-reviewed（ルーティングタスクはディスパッチをテストします。信頼する前に、品質を評価するタスクへと厳密化してください）
既存のスキルを反復的に改善する	gbrain skillopt foo --benchmark skills/foo/skillopt-benchmark.jsonl
費用のかかる実行のプレビューを確認したい	--dry-run を追加
同梱スキル（gbrain リポジトリ内の skills/）	デフォルトでは proposed.md に書き込みます。同じ場所で変更を確定するには --allow-mutate-bundled と --held-out <path>（ベンチマークと重複しないタスクが 5 個以上）を追加します。そうしないと、明示的に拒否されます。プラグインのインストール環境では、同梱スキルを同じ場所で変更できません（スナップショットは読み取り専用です）。反復作業を行うには SKILL.md を自分の skills ディレクトリにコピーするか、デフォルトの proposed.md レビューフローを使用してください
適用前に変更をレビューしたい	--no-mutate を追加します（proposed.md に書き込みます。held-out は不要です）
ベンチマークへの過剰適合を防ぎたい	--held-out <path> を追加します。ベンチマークでは勝る候補でも、held-out セットで性能が低下する場合は拒否されます
実行途中でクラッシュした	gbrain skillopt foo --resume <run-id>

出力形式

呼び出されると、このスキルは以下を生成します。

• skills/<name>/SKILL.md（変更が許可されている場合）
• skills/<name>/skillopt/best.md — 現在のベスト版のコピー
• skills/<name>/skillopt/versions/vNNNN_eN_sN.md — ステップごとのスナップショット
• skills/<name>/skillopt/history.json — 追記専用の実行記録
• skills/<name>/skillopt/rejected.json — 件数に上限のある、LRU 方式の却下済み編集履歴
• ~/.gbrain/audit/skillopt-YYYY-Www.jsonl — ISO 週単位でローテーションされる監査証跡

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェントオペレータープロトコルに従ってください。このスキルに固有の事項は以下のとおりです。

• ハード拒否：dirty_tree（スキルの編集を先にコミットまたはスタッシュしてください）、d_sel_too_small（ベンチマークタスクを追加してください）、--allow-mutate-bundled と --held-out を指定していないバンドル済みスキル（終了コード 2）。入力を修正してください。無理に続行してはいけません。
• コストの事前チェックで --max-cost-usd を超える場合、またはユーザーが上限を設定している状態で no_pricing が発生した場合は、--dry-run でプレビューし、上限を引き上げる前にユーザーに確認してください。
• skill_candidate_invalid：候補が保護対象のフロントマターを変更したか、本文が空になっています。候補を破棄して報告してください。

アンチパターン

• 検証ゲートを迂回してはいけません。 中央値 3 件＋イプシロン＝0.05 の検証は不可欠です。これがなければ、オプティマイザーはノイズを改善として受け入れてしまいます。
• --allow-mutate-bundled と --held-out の両方を指定せずに、バンドル済みスキルを最適化してはいけません。 バンドル済みスキルは gbrain とともに配布され、後続のエージェントにとって不可欠です。インプレースでの変更には両方のフラグが必要です（ベンチマークと重複しないタスクを 5 件以上含む held-out セット）。held-out セットがない場合、実行はハード拒否され、proposed.md を案内します。
• ブートストラップの出力を強化せずに使ってはいけません。 --bootstrap-from-skill と --bootstrap-from-routing は、いずれもオプティマイザーのモデルに成功基準を考案させます。デフォルトでは汎用的で弱い基準になります。SkillOpt がそれを基準に最適化する前に、評価基準を見直して厳格化してください。そうしないと、スキルは実際の品質ではなく、ベンチマークの成果物に向けて訓練されます。
• 約 15 件のタスクで構成されるスターターでは、--split 1:1:1 を省略してはいけません。 デフォルトの 4:1:5 分割では、検証セットが D_sel >= 5 の下限を下回り、実行が d_sel_too_small で中断されます。

契約

runSkillOpt(opts) は以下を返します。

{
  outcome: 'accepted' | 'no_improvement' | 'aborted' | 'errored',
  receipt: {
    run_id, skill_sha8, benchmark_sha8, models, cost,
    baseline_sel_score, best_sel_score,   // real measured baseline (no longer hardcoded 0)
    baseline_test_score, test_score,      // final held-out test-split eval
  },
  finalText: string,
  mutatedSkillFile: boolean,
  proposedPath?: string
}

関連スキル

• skillify — 新しいスキルのひな形を作成します（skillopt の前に使用してください）
• skillpack-check — スキルの適合性を監査します（項目 13 に skillopt の状態が表示されます）
• conventions/quality.md — skillopt が評価基準を通じて適用する出力品質基準