improve-skill-for-sonnet

name	improve-skill-for-sonnet
description	既存スキルをSonnetなど小さいモデルで実行しても品質が下がらないように改善する。 静的分析→ba提案→承認後適用→Sonnet subagentでの改善前後A/B検証まで一気通貫で行う。 「Sonnet向けに改善」「Sonnet対応にして」「小さいモデルでも動くように」「Sonnet耐性」 「improve-skill-for-sonnet」「モデルを下げても品質が落ちないように」「Haiku/Sonnetで実行する予定のskillを改善」 などのリクエストで使用。skillの実行モデルを下位モデルに切り替える予定がある文脈でも必ず使用する。

Improve Skill for Sonnet

賢いモデル（Fable/Opus）で書かれ運用されてきたskillは、書き手が「行間を読める」前提で書かれている。Sonnetなど小さいモデルは指示追従は得意だが、行間の補完・暗黙前提の推測・途中での自己修正が弱い。このskillの仕事は、対象skillの「行間」を明文化し、実際にSonnetで実行して品質が維持されることを検証すること。

引数 $ARGUMENTS で対象skillのパス（またはskill名）を受け取る。省略時はAskUserQuestionで確認。

実行の分担: このskillの実行者（あなた）は賢いモデル。検証subagentだけが model: "sonnet" で動く。

Sonnetがつまずくパターン

静的分析（フロー2）でこのテーブルを基準に問題箇所を洗い出す。

#	パターン	例	改善方法
1	暗黙の前提	「ノートに追記する」（どのセクション？形式は？）	前提を明文化。参照先があるならパスを明記
2	曖昧な判断語	「適切に」「必要に応じて」「いい感じに整理」	判断基準を具体化。基準→動作のテーブル化
3	散文に埋もれた条件分岐	「AならXするが、Bの場合で〜のときはY」	条件→対応のテーブルまたは番号付き分岐
4	手順の依存関係が暗黙	手順の順序入れ替え・スキップが起きる	番号付き手順＋「Nの前にMが必須。理由: 〜」
5	worked exampleの欠如	変換ルールだけで入出力例がない	実際の入力→期待出力のペアを1〜2個追加
6	エッジケース未定義	対象が0件のとき、ファイルがないとき	状況→挙動のテーブル追加
7	出力形式の自由度過剰	「レポートする」（構造未指定）	出力テンプレートを固定
8	意図の説明不足	理由なしの禁止事項	「理由: 〜」を付ける。意図が分かれば応用が利く

過剰改善への警告: 明文化＝長文化ではない。冗長な説明はSonnetにとってもノイズになり、かえって精度を下げる。1箇所の改善で追加するのは数行まで。テーブル・例・テンプレートなど構造化された短い追記を優先し、散文の説明を足すのは最後の手段。

処理フロー

1. 対象skillの読み込みと副作用分類

対象のSKILL.md全体（references/等の付属ファイル含む）をReadし、副作用レベルを判定して検証モードを決める。

副作用レベル	例	検証モード
read-only	検索・分析・レポート系	通常実行
ローカル書き込み	vault内ノート編集、ファイル生成	コピーに対して実行（対象ファイルをscratchpadに複製し、テストプロンプトでコピーのパスを指定）
外部副作用	メール送信、カレンダー変更、Web投稿、家計簿入力	計画出力モード（subagentに「実行計画・実行するはずのツール呼び出し列の出力まで」を指示。実環境には触れさせない）

2. 静的分析

「Sonnetがつまずくパターン」テーブルの8観点で問題箇所を列挙する。各問題に以下を付ける:

• 該当箇所（行番号または引用）
• パターン番号（1〜8）
• 深刻度: high（Sonnetがほぼ確実に誤動作）/ medium（ばらつき要因）/ low（軽微）

3. テストプロンプトと要件チェックリストの固定

対象skillのdescriptionと本文から、現実的なテストプロンプトを2〜3個（典型ケース1 + エッジケース1〜2）生成する。抽象的な指示文ではなく、実際のユーザーが打ちそうな具体的な文面にする（実在しそうなファイルパス、具体的な内容を含む）。

各テストプロンプトに要件チェックリスト（3〜7項目、[critical] タグ付き項目を最低1つ）を定義する。これが改善前後の採点基準になるため、実行前にここで固定し、以後変更しない（後から動かすと採点が恣意的になる）。

テストプロンプトとチェックリストをユーザーに提示して確認を取る。ユーザー確認が不可能な状況（subagentとして実行中など）では推奨案のまま進み、最終レポートに「確認省略」と明記する。

4. ベースライン実行（改善前 × Sonnet）

Agentツール（subagent_type: "general-purpose", model: "sonnet"）で、改善前の対象skillを使ってテストプロンプトを実行する。各プロンプト2回（結果のばらつきが大きい場合のみ3回目を追加）。全実行を1メッセージで並列起動する。

subagentへの指示テンプレート:

あなたはskillを読んで実行するエージェントです。
1. <対象skillのパス> を読み、その指示に従って以下のタスクを実行してください。
2. タスク: <テストプロンプト>
3. <検証モードに応じた指示: 通常実行 / 対象は○○のコピーです / 実行計画の出力までで止めてください>
4. 完了後、以下を報告してください:
   - 成果物（または成果物のパス）
   - skillの指示で不明瞭だった点（箇条書き。なければ「なし」）
   - 自分の裁量で埋めた判断（skillに書かれていなかった決定。なければ「なし」)

各実行の結果を要件チェックリストで採点する（○=1点、partial=0.5点、×=0点。達成率% = 合計/項目数）。[critical] が1つでも×なら、その実行は失敗扱い。

各ランの成果物とsubagentの報告全文をscratchpad配下に保存する（例: runs/baseline/prompt1-run1/、改善後は runs/improved/）。理由: レポートに書く実測値を後から裏取りできるようにするため。改善前スナップショットも SKILL.md.baseline-backup 等として残す。

5. ba提案と適用

静的分析（フロー2）とベースラインで実際に落ちた箇所（フロー4）を突き合わせ、改善案を作る。ベースラインで実際に問題が出た箇所を最優先にする（静的分析だけの推測改善は深刻度highに限定。理由: 実証なしの改善は過剰改善になりやすい）。

改善案はBefore/After形式でユーザーに提示し、承認を得てからEditで適用する。

改善時の制約:

制約	理由
元のskillの意図・機能範囲を変えない	改善であり再設計ではない
frontmatter descriptionのトリガーワードを維持	変えるとskillの発火条件が変わってしまう
[[]]リンク・#タグ等のskill固有記法を保持	vault系skillでは実データの一部
推測で新情報を追加しない	誤った明文化は暗黙前提より有害

6. 改善後実行とA/B比較

改善後のskillで、フロー4と同一のテストプロンプト・同一の回数・同一の検証モードでSonnet subagentを実行する。

採点は固定済みの要件チェックリストに対して行う。改善前後の出力を並べて「どちらが良いか」を直接判定しない（position bias・自己選好biasで小サンプルでは信頼できない。empirical-prompt-tuningの知見）。比較は以下の客観指標のみ:

指標	取得元
達成率の平均と各回の値	チェックリスト採点
[critical] 失敗の有無	チェックリスト採点
不明瞭点・裁量判断の件数	subagentの自己報告
tool_uses / duration	Agentツールのusage meta

7. レポート

以下の形式で報告する:

## improve-skill-for-sonnet レポート: <対象skill名>

### 改善サマリー
| パターン | 変更数 |（変更したパターンのみ列挙）

### A/B検証結果
| テストプロンプト | 改善前 達成率 | 改善後 達成率 | critical失敗 前→後 |
|---|---|---|---|

### 改善前のSonnetで実際に起きた問題
- <プロンプトN>: <何が起きたか> → <どの変更で対処したか>

### 残課題
- <改善後もばらつく箇所、今回対象外とした箇所>

改善後に達成率が下がった場合は、該当の変更を特定してrevertを提案する（改善の押し付けをしない）。

関連スキル

skill	住み分け
optimizing-docs-for-ai	汎用のAI向けドキュメント最適化（静的のみ）。本skillは「小さいモデルでの実行品質」特化で、Sonnet実行検証まで行う
empirical-prompt-tuning	実行モデルを固定した厳密な反復改善の方法論。収束判定つきの複数イテレーションが必要ならそちらを使う。本skillは1〜2往復の改善に最適化