improve-skill-quality

スキルの品質を改善する

失敗した評価や説得力のない評価を、的を絞った修正につなげます。このリポジトリで最もよくある間違いは、実際の原因が評価、フィクスチャ、またはハーネスにある判定に対して、スキルの説明文を書き換えてしまうことです。まず原因を分類し、それから修正してください。

使用する場面

• 評価結果がリグレッション、検出力不足、または「信頼できる改善なし」と判定された場合。
• スキルが単独のアームでは勝つ一方、プラグインのアームでは勝てない、または「有効化されなかった」と報告された場合。
• /evaluate が「評価は実行されましたが、結果は生成されませんでした」と報告した場合。
• スキルのスコアは高いものの、コスト（トークン数、ターン数、実行時間、プラグインメニューの予算）が高すぎる場合。
• 継続的に弱いスキルを強化するか、廃止するかを判断する場合。

使用しない場面

• スキルをゼロから作成する場合 — create-skill を使用してください。
• 新しい eval.yaml をゼロから作成する場合 — create-skill-test を使用してください。
• ハーネス自体（eng/skill-validator、eng/vally-adapter、evaluation*.yml）を変更する場合。

入力

入力	必須	説明
判定の証拠	はい	/evaluate の PR コメント、または実行アーティファクトの results.json
敗北した試行のトランスクリプト	内容を修正する場合は必須	ベースラインとスキル適用後の出力、および判定者が示した理由
刺激ごとの投票 W/T/L と反復実行の W/T/L	はい	タスク横断の証拠と信頼性を区別します
アームごとの有効化状況	はい	単独での有効化とプラグインでの有効化は、それぞれ異なる失敗です

ワークフロー

ステップ 1：仮説を立てる前に証拠を集める

アーティファクトをダウンロードして results.json を読む方法については、InvestigatingResults.md を読んでください。失敗した刺激ごとに、以下を抽出します。

• 正式な刺激ごとの投票 W/T/L と、別途記録された反復実行の W/T/L
• 単独アームとプラグインアーム、それぞれの有効化状況
• 敗北した各試行について、判定者が示した理由の逐語的な記録
• エラー、タイムアウト、または空の出力になった試行があるか

敗北した試行とその理由を引用できるようになるまで、スキルの内容を変更しないでください。他の原因クラスでは、必要な証拠が異なります。ハーネスの失敗はジョブログと仕様から診断し、検出力の問題は試行記録から診断します。どちらにも引用できる敗北試行はなく、それを要求すると、かえって説明文の書き換えに走ることになります。

ステップ 2：失敗を分類する

以下の表を上から順に確認し、最初に当てはまった行で止めてください。各行は、症状がスキルの内容の問題と誤診された頻度の高い順に並んでいます。フィクスチャの失敗は、セットアップや信頼性の問題としても現れ、そのように誤分類されるため、フィクスチャの行を先頭にしています。

症状	実際の原因クラス	参照先
フィクスチャがビルドできない、git で追跡されていない、誤った理由で失敗する、または内容が矛盾している	フィクスチャ	ステップ 4
results.json がない、「結果は生成されませんでした」と表示される、または仕様が読み込まれていない	ハーネス／仕様の読み込み	ステップ 3
試行でエラーが発生した、タイムアウトした、または空の出力が返された	信頼性	ステップ 3
軌跡が一致しない、試行でエラーが発生した、またはサマリーと一致しない — 判定が確定不能と報告された	信頼性（検出力ではない）	ステップ 3
肯定的な記録（例：16W/8T/1L）があり、比較結果も確定しているのに、判定が合格ではない	統計的検出力	ステップ 5
設計上、スキル適用アームがベースラインアームと同一である	評価設計	ステップ 6
有効化されているが、品質面で敗北し、判定者が具体的な欠陥を指摘している	スキルの内容	ステップ 7
単独では有効化されているが、プラグインでは有効化されていない	有効化／ルーティング	ステップ 8
どちらのアームでも有効化されていない	フロントマターの説明	ステップ 8
勝っているが、ベースラインよりはるかにコストが高い	スコープとコスト	ステップ 7

比較が確定している場合にのみ、判定は測定済みの結果となります。adapt.mjs は、エラーが発生した試行がゼロ、一致しない軌跡がゼロ、かつサマリーが一致している場合にのみ、合格またはリグレッションを報告します。記録を検出力の問題とみなす前に、これを確認してください。

ステップ 3：ハーネスと信頼性の問題を除外する

問題の全一覧については、references/eval-triage.mdを参照してください。よくあるものは次のとおりです。

• リポジトリのゲートは、非推奨のトップレベルのconfig:エイリアスを拒否します。また、Vallyはconfig:とdefaults:の両方を宣言した仕様を拒否します。このエイリアスを1つのdefaults:ブロックに置き換えてください。
• 試行のエラーは、必ずしもフィクスチャの問題ではありません。判定側の認証エラーとsession.idleエラーは判定結果からは同じように見えるため、SDKのバージョンを固定するのではなく、ハーネスを修正する必要があります。
• アドバイザリー形式の質問にexpect_tools: [bash]を指定すると、復元またはビルドを強制し、品質向上なしに回答がタイムアウトします。
• 実際のコード生成を促す刺激には、およそ360秒が必要です。タイムアウトすると出力が空になり、すべての採点器で失敗し、実際の品質を示すシグナルが見えなくなります。
• 軌跡が一致しない場合、試行にエラーがある場合、または要約が一致しない場合、比較は結論不能です。一致している残りの試行には偏りがあるため、記録は測定済みの帰無結果ではなく、検出力や内容の問題として解釈してはいけません。
• 汎用のYAMLパーサーは本番用ローダーではありません。Vallyがスキル評価を拒否した場合、またはネイティブSDKのレーンがエージェント評価の実行可能なシナリオフィールドを拒否した場合は、内容を変更する前にハーネスまたは仕様の読み込みの問題として分類してください。ネイティブのエージェントパーサーはゴールデン参照を無視するため、check_eval_quality.pyと決定論的なゴールデンワークスペースのリプレイを別途使って検証してください。
• ワーカー1つでの合格や、ローカルのタイムアウトを延長しての合格は、通常の実行を示す証拠にはなりません。リポジトリの通常の並行数と宣言されたスイートの予算で再現してください。そこで失敗するなら、それは信頼性の欠陥です。

ステップ 4：スキルに手を加える前にフィクスチャを確認する

python eng/eval-quality/check_eval_quality.pyを実行してください。ここでは、実際の評価結果を損なう可能性のある22種類の欠陥を検出します。その後、以下を手作業で確認してください。

• 各フィクスチャが、刺激の想定どおりに動作すること。正常であることを意図したフィクスチャはビルドに成功し、壊れていることを意図したフィクスチャは、刺激の対象である理由そのものによって失敗し、ほかの理由では失敗しないこと。
• 参照される各フィクスチャがディスク上にあるだけでなく、gitインデックスに含まれていること（git ls-files）。.gitignoreが、コミット対象のカバレッジ用フィクスチャを気付かないうちに除外していた事例があります。
• 1つのフィクスチャが、互いに矛盾する同じ事実を複数の場所で示していないこと。line-rateの宣言値、サマリーの合計値、<line>要素が一致しないCoberturaレポートが典型例です。または、2つのアームがそれぞれ正当に異なる情報を参照していること。
• 保持やスコープに関する各アサーションが、代表的な1つのファイルだけでなく、対象範囲内のファイル一式全体を網羅していること。
• ゴールデン軌跡とパッチが決定論的な採点器に合格し、現実的な不具合を再現する変更が、対象の動作を保護する採点器で失敗すること。

ステップ 5：評価が合格し得るものだったかを確認する

ゲートには独立した2つの基準があり、これらを混同することが誤診の原因になりがちです。

1. 異なる刺激数が5以上であること。 これを下回ると、判定はunderpoweredと報告されます。合格にも回帰にもなりません。
2. 符号検定で、不一致（引き分けではない）刺激の票についてp ≤ 0.05に達すること。 引き分けは黙って除外されるわけではなく、不一致数を抑えます。

不一致の刺激票	合格となる記録	p
≤ 4	スキルの出来にかかわらずなし	≥ 0.0625
5–7	敗北が0の場合のみ（5W/0L）	0.031
8	敗北1回まで許容（7W/1L）	0.035

したがって、刺激がちょうど5つの場合、引き分けが1つあるだけで致命的です。不一致が4つに減ってしまいます。刺激が6つなら引き分け1つまでは許容され（5W/1T/0L）、7つなら2つまで許容されます（5W/2T/0L）。敗北は許容されません。

そのため、記録が良好なのに判定に失敗する場合は、内容ではなく検出力の問題です。判別力のある刺激を追加して解決してください。runsを増やすと同じタスクの信頼性を測定できますが、最低基準は満たせません。

ステップ 6：2 つのアームに違いがあるか確認する

スキルとスキル自体を比較する評価では、判定者のノイズを測ることになります。

• 休眠ガード（expect_activation: false）では、constraints.reject_skills も設定してはいけません。 これによりスキルありのアームからスキルが除外され、起動契約で乗っ取りを検出できなくなります。 スキーマバージョン 4 では診断用に同一アームの比較を保持しますが、選好の推定からは除外します。 予期しない単独での起動があれば、引き続き合格を阻止します。
• disable-model-invocation: true のスキルは、モデル向けのスキルありアームに含まれません。 そのため、評価者が起動を調べるか回答内容を調べるかにかかわらず、直接評価では同一のアームを比較することになります。 代わりに、利用者の成果を通じて評価してください。たとえば、filter-syntax は run-tests と mtp-hot-reload で評価できます。
• config に必須キーがない評価者は何も適用しないため、刺激には見かけよりもアサーションが 1 つ少なくなります。

ステップ 7：負けた試行を基にスキルの内容を修正する

ここで初めてスキルを変更します。references/writing-for-baseline-delta.md のパターンを適用してください。特に、敗北を覆すことの多いものは次のとおりです。

• モデルがすでに知っている説明文を、そうしなければ誤る判断に置き換えます。
• 強力なスキルが過剰に適用されないよう停止条件を追加します。ただし、ベースラインよりも狭い範囲に回答を過度に限定しないでください。
• 出力の構成を入力の規模に合わせます。8 件のテストスイートに対するダッシュボードは、直接的な回答に負けます。
• 検証結果を正確に報告するよう求めます。復元に失敗した後で「ビルドに成功しました」と主張すると、自動的に敗北となります。
• 重要な API に関する主張は、ソースを読むのではなく、コンパイルまたはプローブによって検証します。
• コストが悪化した場合は、まれな処理や高コストの処理を references/ の読み込みの後に行うようにし、オーケストレーションの規模をユーザーの範囲に合わせます。

ステップ 8：起動を修正する

起動の失敗は、本文ではなくフロントマターとルーティングの失敗です。references/eval-triage.md を参照してください。概要は次のとおりです。

失敗	修正
どのアームでも起動しない	description にユーザー自身の言葉を入れます。症状、エラーコード、成果物名、引用された依頼などを記載します
別のスキルがプロンプトに選ばれる	description で曖昧な語句を正確に取り上げ、両方のスキルに対応する除外条件を追加します
スキルをまったく使わずにモデルが回答する	説明で重要性を高め、プラグインメニューの混雑を緩和し、プラグインアームで検証します
境界条件によって実際のシナリオが除外される	すべての「次の場合には使用しない」条項を、各評価プロンプトおよび実際のワークフローの各段階と照らし合わせて再確認します
description が 1,024 文字の上限に達している	トリガーフレーズではなく、本文と重複する内容を削ります。プラグインメニューの予算も確認します

ステップ 9：再検証する

dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin>
python eng/eval-quality/check_eval_quality.py
./eng/run-skill-evals.sh <plugin> <skill>

通常のワーカー並行性と、宣言された defaults.timeout を使用して、本番環境の経路で実行します。スキル評価には Vally を、エージェント評価には skill-validator evaluate を使用してください。エージェント評価では、別途 check_eval_quality.py を実行し、各ゴールデンパッチをマテリアライズされたフィクスチャに適用し、該当する決定論的なファイル、出力、コマンドの各評価者をゴールデン結果に対して実行します。シリアル実行のみの合格や、その場限りで増やした予算を完了の証拠として使用しないでください。ルーティングや動作に広範な変更を加える場合は、GPT 系と Claude 系の結果を分けて収集します。異なるモデル系統の結果をまとめて、追加の刺激票として扱わないでください。

続いて、レビュー対象のコミットに実行を紐付けるため、/evaluate を含む PR レビュー（Files changed → Review changes）を送信して、公式実行を依頼します。結果を見て回帰と判断する前に、スキルのペイロードが実際に変更されたことを確認してください。バイト単位で同一の内容を再実行した結果は、7W/2T/2L から 4W/5T/2L に変化したことがあります。

検証

• コンテンツを修正する場合、負けた試行と、その理由として審査者が述べた内容が PR の説明に引用されています。
• コンテンツを編集する前に、失敗が分類されています。
• check_eval_quality.py と skill-validator check の両方が成功します。
• 本番環境のスキルまたはエージェントランナーが実行可能な仕様を受け入れます。
• ゴールデンリファレンスがスタンドアロンチェッカーと決定論的リプレイを通過します。
• 評価が通常の並列実行数と宣言された時間予算内で完了します。
• ゴールデンの受け入れとミューテーションの拒否が実証されています。
• 刺激の種類の数が、対象とする効果と観測された同率の割合に対する検出力の基準を満たしています。
• 単独での有効化とプラグイン経由での有効化の両方が報告されています。
• 広範な変更について、GPT 系と Claude 系それぞれの根拠が示されています。
• PR の本文に根本原因、修正内容、検証結果が記録され、教訓を再利用できるようになっています。

よくある落とし穴

落とし穴	解決策
検出力不足の判定を受けてスキルの文章を書き直す	検出力不足は、種類の異なる刺激が少なすぎるという意味です。代わりに、識別力のある刺激を追加してください
非推奨のトップレベルの config: エイリアスを使う	defaults: に名前を変更して設定を維持してください。リポジトリのゲートはこのエイリアスを拒否します
刺激数の下限を満たすために runs を水増しする	繰り返しは1つのタスクに対する信頼性を測定します。刺激を追加してください
エラーになった試行をフィクスチャの非決定性として扱う	まず stderr を確認してください。審査側の認証エラーにはハーネスの修正が必要です
フィクスチャが実際に誤りとした「誤った」回答を修正する	回答を非難する前に、フィクスチャの整合性を確認してください
誰も使わず、何も通過しないスキルを強化する	評価シグナルが弱く、テレメトリも乏しい場合は、廃止が妥当です
再実行せずに修正を取り込む	呼び出されたペイロードに修正が含まれていることを確認してください。審査の揺らぎは実際に起こります

参考資料

• references/writing-for-baseline-delta.md — スキルなしのモデルを上回るコンテンツパターン
• references/eval-triage.md — PR の引用を含む、症状、原因、修正の一覧
• eng/eval-quality/README.md — 22 個の構造ゲートチェックと、それぞれの目的
• eng/vally-adapter/InvestigatingResults.md — 成果物のダウンロードと results.json の読み方。こちらが現行のガイドです。同様の名前を持つ eng/skill-validator/src/docs/InvestigatingResults.md は、廃止された skill-validator evaluate のスキーマを説明するもので、現在の結果については説明していません。