skill-eval-improve

スキルの評価と改善

スキルを測定可能な形で改善します。ベースライン → 測定 → 範囲を限定した編集 → 再検証の順に進めます。ローカルツール、Codex plugin-eval（インストールされている場合）、研究に基づく改善サイクル（SkillOpt）を組み合わせます。

使用する場合

• スキルが誤ってトリガーされる、またはまったく読み込まれない場合（説明文によるルーティング）
• SKILL.md が肥大化している、トークンコストが高い、成果が乏しい場合
• 新しい手順を追加した後に、リグレッションチェックが必要な場合
• 製品 MCP や plugin-eval の研究から得たパターンを Skill Steward のスキルに取り入れる場合

使用しない場合

• リポジトリ全体の一括検証 — 例：「このリポジトリのすべてのスキルを検証する」→ pnpm run validate のみを実行します（監査には skill-authoring-lifecycle を参照）。ベンチマークや SkillOpt の改善サイクルは開始しないでください。
• SkillOpt による自動化／クラスタートレーニング — Skill Steward が説明しているのは、範囲を限定した手動の編集サイクルです。一晩中稼働する最適化パイプラインはありません。
• 新しいスキルの作成 — まず skill-authoring-lifecycle を使用します。評価と改善は、スキルが作成された後に適用します。

Cursor のスコープ（任意）：skills/** または scripts/validate-skills.mjs の下を編集するときに有効化します。

混合エキスパート方式（評価スタック）

レイヤー	エキスパート	ツール／手法	コスト
0 — ゲート	リント	pnpm run validate、skill-authoring-lifecycle	数秒
0b — ルール	ルーティング／ドキュメントの SSOT	pnpm run eval（T1 の動作上重要な YAML ケース）	数秒
1 — 静的	構造	Codex plugin-eval analyze（利用可能な場合）	数秒
2 — 人手	動作	スキルあり／なしで 3～5 個のプロンプトを実行	数分
3 — 測定	使用状況	plugin-eval benchmark ＋ measurement-plan	数分～数時間
4 — 改善	テキスト最適化	SkillOpt 方式の範囲を限定した編集 ＋ ホールドアウトゲート	数時間
5 — 案内	テレメトリ／ドッグフーディング	コンパクトなトレースでの現在の steward benchmark シナリオ	数秒

質問に答えられる最も低コストのレイヤーを使用してください。レイヤー 0 は省略しないでください。

レイヤー 0 — Skill Steward バリデーター（常に実行）

pnpm run validate
pnpm run validate:json   # CI / automation

すべての error: 行を修正してください。warn:（sources.md の欠落、長すぎる SKILL.md）は重大なものとして扱ってください。

T で始まるスキル品質ゲート（ADR 0011、ADR 0027）

ティア	スキル	CI
T1 — 動作上重要で評価ゲートあり	ドリフトによってエージェントの判断、主張、委任、ガバナンス、またはエビデンスの境界が変わる可能性のあるルーティング／手順スキル	pnpm run eval ＋ validate
T2 — 構造検証のみ	その他すべて	pnpm run validate

現在、T1 の動作上重要なスキルには、harness-engineering-lifecycle、mcp-harness-repo-maintainer、mixture-of-experts、multi-agent-handoff、plugin-marketplace-setup、repo-quality-system-lifecycle、repository-governance-lifecycle、skill-authoring-lifecycle、skill-eval-improve、steward-continuity-boundary-lifecycle、vision-alignment-foresight が含まれます。それぞれに evals/cases/*.yaml（2 件以上）と references/evals.md が必要です。スキーマ：eval-case-schema.md。

レイヤー 0b — ルールベースのケース（T1 の動作上重要な CI）

pnpm run eval
pnpm run eval -- --skill mcp-harness-repo-maintainer
pnpm run eval:json

Chrome の評価設計（失敗モード、評価基準、客観的評価と評価者による判断）：references/chrome-eval-design.md。

CI では LLM 評価者を実行しません。主観的な品質評価は references/evals.md（レイヤー 2 以降）に記載します。

レイヤー 1 — Codex plugin-eval（ローカル）

Codex の plugin-eval がインストールされている場合（~/.codex/plugins/.../plugin-eval）：

# Chat-first router
plugin-eval start skills/<name> --request "Evaluate this skill." --format markdown

# Static report
plugin-eval analyze skills/<name> --format markdown

# Token budget explanation
plugin-eval explain-budget skills/<name> --format markdown

# Starter benchmark config
plugin-eval init-benchmark skills/<name>
plugin-eval benchmark skills/<name> --dry-run

analyze --brief-out の後、書き換え計画を plugin-eval の improve-skill スキルに引き継ぎます。

詳細：references/plugin-eval.md。

レイヤー 2 — 人間によるプロンプトスイート（大幅な編集では必須）

1. 代表的なユーザープロンプトを3～5件作成します（発動すべきケースと発動すべきでないケース）。
2. スキルを使わずにエージェントを実行し、失敗を記録します。
3. スキルを使って実行し、改善点と新たな失敗を記録します。
4. プロンプトを evals/cases/*.yaml（CI ルール）と references/evals.md（動作ログ）に反映します。

約60％を訓練用（編集時に使用）、40％を保留用（受け入れ判定用）に分割します。これは SkillOpt の選択ゲートを模したものです。

レイヤー 3 — SkillOpt に着想を得た改善ループ（調査）

SkillOpt は、エージェントを固定したまま、SKILL.md を訓練可能なテキストとして扱います。

Rollout (tasks + current skill) → Reflect (failures vs successes)
  → Bounded edit (add/delete/replace under budget) → Held-out gate (keep only if better)

Skill Steward による手動での適応（GPU クラスターは不要です）。

手順	アクション
1	ベースライン：スキルなしでの保留タスクの合格率
2	スキルあり：同じタスクの合格率を記録
3	振り返り：具体的な失敗モードを1～3件列挙
4	編集範囲を制限：変更行数は10％以下、または新しいセクションを1つだけ追加します。全面的な書き換えはしません
5	保留分のみ再実行し、改善した場合にのみ編集を採用
6	結果を references/evals.md と sources.md に記録

論文：https://arxiv.org/abs/2605.23904 · サイト：https://microsoft.github.io/SkillOpt/

関連：SkillLens（モデル生成スキルの研究）。

レイヤー 4 — エコシステムのベンチマーク（2026年以降）

リソース	用途
SkillsBench	標準タスクとスキル拡張タスクを対比するアプローチの参考
skillgrade	スキル品質の回帰テスト（mgechev）
Claude の作成に関するベストプラクティス	作成前に評価するワークフロー

レイヤー 5 — 実行時のドッグフードベンチマーク

規模が10,000倍になると、LLM は膨大なツールセットの操作によって認知過負荷に陥るため、NLP プロンプト評価では不十分です。実行時のドッグフードでは、決定論的なトレースを使って論理的な実行経路を客観的に検証します。

1. コンパクトなトレースを取得する： 生の製品トレースではなく、アクション ID、ツール数、成果物のダイジェスト、編集済みの抜粋を保存します。
2. アサーションを定義する： 期待されるアクションの実行経路、最初に使用する宣言済みのサーフェス、最大ツール呼び出し回数、最大修復／セットアップ試行回数、最大無関係なツール呼び出し回数、必須の return_to_goal_step、必須成果物、無関係なアクションに対する否定チェックを定義します。
3. ドッグフードベンチマークを実行する： 実行時のドッグフードシナリオには steward benchmark --scenario <id> --json を使います。製品の実行時シナリオを、動作に不可欠なスキルの評価である T1 に含めないでください。

現在の steward eval --name 登録済み評価パスは、レガシー／実験段階のものです。スキルの品質評価には引き続き pnpm run eval を使い、実行時のドッグフードには steward benchmark を使います。契約入力が変更されているか未追跡の場合、durability_blocked は有効なブロック証拠となりますが、実行時の動作を証明するものではありません。

改善ワークフロー（チェックリスト）

- [ ] sources.md cites plugin-eval + SkillOpt if used
- [ ] pnpm run validate
- [ ] T1 behavior-critical: `pnpm run eval` + cases updated
- [ ] plugin-eval analyze (optional)
- [ ] 3+ prompt evals documented in references/evals.md
- [ ] Bounded edit applied; held-out improved
- [ ] skill-authoring-lifecycle checklist
- [ ] PR mentions eval delta

先に修正する項目（一般的な順序）

1. name / description（ルーティング）—何をするか、いつ使うかを含める必要があります
2. 壊れたリンク／不足している references/sources.md
3. 新しいセクションや評価ケースを追加する前に、重複したルールを削除または置き換える
4. 大量の内容を references/ に移動する（SKILL.md は500行未満）
5. エージェントが省略するエラー処理／検証手順を追加する
6. トークンコスト（説明の長さ、常時読み込みされるコンテンツ）

アンチパターン

• 失敗1件をもとに SKILL.md 全体を書き換える（機能しているルールを壊す）
• 保留プロンプトを使わずに自己編集する（過学習）
• より小さな FAQ、エラーメッセージ、ネイティブコマンド、観測された効果の確認、または削除で問題を解決できるのに、観測された実行1回を根拠にスキルのルール、評価、ツールを追加する
• 重複したガイダンスに対し、重複するルールを圧縮、削除、置換する前に新しい評価を追加する
• references/sources.md の記載を伴わない主張
• 静的解析だけで評価し、実際のプロンプトを一度も実行しない
• CI で LLM ジャッジを使う（不安定でコストがかかる）—ADR 0011 に従い、オフラインでのみ実施
• pnpm run eval の合格をもってエージェントの動作が証明されたと主張する

Related skills

Skill	Role
skill-source-citations	Save research links
skill-authoring-lifecycle	Scaffold
skill-authoring-lifecycle	Pre-merge audit

Sources

See references/sources.md.

Install

npx skills add arenukvern/skill_steward --skill skill-eval-improve