Testing Agent Skills Systematically with Evals（Evals で Agent Skills を体系的にテストする）は、2026 年 1 月 22 日に OpenAI の開発者ブログで公開された実践的なガイドであり、OpenAI Codex 向けのスキル（Agent Skills の意味でのスキル）を、テストし、採点し、時間をかけて改善できる対象として扱う方法を解説している。出発点となる問題は、スキルを反復的に改善しているとき、ある変更がスキルを改善したのか、単に振る舞いを変えただけなのかを見分けにくいこと、そしてリグレッションが入り込むことである。スキルが起動しない、必須のステップを飛ばす、余計なファイルを残す、といったものだ。
この記事の前提は、スキルとは LLM 向けのプロンプトと指示を整理した集まりであり、したがってスキルを改善する最も確実な方法は、他のプロンプトと同じように評価することだというものである。記事は eval を、プロンプト、記録された実行（トレースと成果物）、少数のチェック、そして時間を追って比較できるスコアとして定義しており、実際には軽量なエンドツーエンドテストに近いものだと述べている。解説では、意図的に最小限にとどめたサンプルスキル setup-demo-app を用いる。これは、固定されたファイル構成と明示的な完了の定義を持つ小さな React のデモアプリをスキャフォールドするスキルである。
要点
- 成功は、スキルを書く前に測定可能な形で書き出しておくべきであり、成果目標（タスクが完了したか）、プロセス目標（Codex がスキルを呼び出し、意図されたツールとステップに従ったか）、スタイル目標（出力が要求された規約に従っているか）、効率目標（空回りせずにそこまで到達したか）に分ける。記事は、このリストを小さく保ち、必ず合格すべきチェックに限定することを勧めている。
- Codex のスキルは
SKILL.mdファイルを持つディレクトリであり、その YAML フロントマターにはnameとdescriptionが記載される。記事はこれらを、Codex がスキルを呼び出すかどうか、そしてファイルの残りをいつ読み込むかを判断するための主要なシグナルとして特に取り上げており、曖昧だったり詰め込みすぎたりした値は起動を不安定にするとしている。 - 最初のパスは手動で行うべきである。実際のリポジトリまたは作業用のリポジトリでスキルを明示的に呼び出し、起動、環境、実行順序についての隠れた前提を探す。記事は、この段階で行った手動の修正はすべて、将来の eval の候補として扱う。
- 1 つのスキルには、10〜20 件のケースからなる小さなプロンプトセットで十分だとされる。サンプルのセットには、明示的な呼び出し、暗黙的な呼び出し、追加のドメイン情報を含む文脈的な呼び出し、そしてスキルを起動すべきでない少なくとも 1 つのネガティブコントロールが混在しており、後者はスキルが過剰に起動してしまう偽陽性を捉えるためのものである。
- 決定論的なチェックは、
codex exec --jsonが JSONL として書き出す構造化されたイベントトレースに対して実行される。たとえばnpm installが実行されたか、package.jsonが作成されたかといったものであり、失敗したチェックの理由をトレースを読んで説明できるようにする。 - コンポーネント構成やスタイリングの規約といった定性的な要件は、2 回目の読み取り専用の
codex exec実行によって採点される。その最終回答は--output-schemaによって、全体の合否、スコア、チェックごとの結果を持つルーブリックの JSON オブジェクトに制約される。 - 記事は、スキルが成熟するにつれてスイートを拡張することを提案している。ループを検出するためにコマンド数を数える、トークン使用量を追跡する、ビルドやランタイムのスモークチェックを実行する、リポジトリがクリーンな状態で残されているかを確認する、スキルが昇格した権限なしで動作するかを確認する、といったものであり、遅いチェックはリスクを減らす場合にのみ追加する。
- 締めくくりの助言は、実際の失敗にカバレッジを導かせることである。開発中や利用中に見つかった取りこぼしはすべてプロンプトセットの新しい行となり、記事はこれを、スキルが今後も正しくこなし続けなければならないことの生きた記録だと表現している。
背景
これは OpenAI が自社のエージェントと CLI について示した自社のガイダンスであり、登場するコマンドはすべて Codex のコマンドである。記事は、この方法を適用して得た測定結果を何も報告していない。その中心的な発想は、最終的な出力の見た目だけでなく、エージェントが何をしたか、すなわちどのコマンドをどの順序で実行し、結果としてどのファイルができたかに基づいてスキルを評価することであり、変更が「良くなった気がする」かどうかを問うことや雰囲気に頼ることと明示的に対比している。そのパターンは、エージェントの記録された行動に対する決定論的なチェックと、ルールでは捉えられないものに対するモデル採点のルーブリックを組み合わせるものであり、高速なチェックから始めて、より遅く重いチェックは確信を高める場合にのみ追加する。