Agent Skillsの作り方 履歴から設計して評価する

Agent Skillsを調べ始めると、SKILL.mdの書式や配置場所はすぐに見つかります。

実際に作り始めて難しかったのは、その先でした。

どの手順をSkillとして切り出すのか。そもそも、その候補をどこから見つけるのか。何を本文に書き、何をreferences/やscripts/へ逃がすのか。作ったSkillが本当に役立ったかを、どう判断するのか。

私がいま一番良いんじゃないかなと思っているやり方・作り方・入口は、CodexとClaude Codeの全履歴を参照することです。AIエージェントが繰り返し失敗した箇所と、私が訂正し、採用または拒否した判断には、次の実行時にも必要になる手順や境界が残っています。ただし、履歴はSkillの候補を見つける材料であって、正しい手順がそのまま手に入る信頼できる情報源ではありません。

私なりの結論は、Skillを長いプロンプトとして書くのではなく、測定できる一つの業務を再現する手順書であり、必要なときだけドメイン知識を開く参考書であり、利用者が明示的に起動できるカスタムコマンドとして設計することです。一つのSkillが、この三つの役割を重ねて持つこともあります。

この記事では、AI AgentのSkillとは何かという概念説明から一歩進み、履歴から候補を見つけ、Agent Skillsを設計・実装・評価・配布する流れをまとめます。Codex・Claude Code・Gemini CLIなど、利用するAIエージェントによってSkillの探索場所やfrontmatter、起動方法は変わり得ます。導入時には、実際に使うAIエージェントの現行ドキュメントも確認してください。

Skillの候補はCodexとClaude Codeの履歴から見つける

Skillの題材を白紙から考えるより、実際の仕事で起きた失敗と訂正を調べる方が確かです。 (手順がすでに明確なら、履歴分析を経ずに手順書やカスタムコマンドとして切り出すこともできると思います)

今回、このリポジトリに対象を限定してローカル履歴を調べました。改訂時に再集計したところ、作業ディレクトリがこのリポジトリと一致するCodexのJSONLは482件、Claude Codeのトップレベルのプロジェクト履歴は13件ありました。.claude/skills/配下にあるSkillディレクトリは17個でした。これらの数字は、Skillを作った後の会話に加えて、作る前の失敗や訂正まで遡れる範囲を示すために挙げています。

履歴からSkillと評価ケースを作るまでには、選別と裏取りが必要です。私は次の流れで考えています。

図の読み方

1. Codexは作業ディレクトリ、Claude Codeはプロジェクトを基準に、このリポジトリに属する履歴を別々に抽出します。
2. 人の依頼・訂正・採否・判断を残し、systemメッセージ、Tool出力、秘密情報、一度限りの事情を候補から外します。
3. 候補を現在のコード、Git、現行ドキュメント、実際の起動と挙動で検証します。
4. 共通する判断とCodex・Claude Codeで異なる判断を分け、Rule・Skill・script・評価ケースへ分類します。
5. 初回は全履歴を調べ、運用後は前回監査からの差分を中心に見直します。

Source

公開後の再集計を含むローカル履歴調査

Method

履歴抽出・人の判断の選別・現在の実装による検証・配置先の分類

Environment

このリポジトリのCodexとClaude Code履歴

図の最初で二つの履歴を混ぜていないのは、保存形式が違うからだけではありません。Codexでだけ繰り返す詰まりと、Claude Codeでだけ繰り返す詰まりを、共通点に丸めて消さないためです。

全履歴を対象にしても抽出結果をそのまま規則にしない

過去のやり取りは、何が必要だったかを知る材料です。ただし、過去に一度そう言ったから、という理由だけで現在の規則にはできません。

最初に見るのは、ユーザーである私の依頼・訂正・判断・採否です。AIエージェント自身の提案やsystemメッセージ、Tool出力を、そのまま私の要件として数えません。そのうえで、次の内容を抽出します。

• 同じ指摘を二回以上受けた箇所
• 作業をやり直す原因になった判断
• 毎回確認しているコマンドやファイル
• ユーザー確認が必要だった操作
• 成功したときだけ含まれていた検証手順

AIエージェントが何度も失敗した箇所、私が同じ訂正を繰り返した箇所、判断に迷って作業が止まった箇所。こうした履歴には、次に同じ仕事をするときも必要になるルールや確認手順が残っています。

うまくいった会話だけを見るより、失敗と訂正の履歴を見た方が、Skillに何を書くべきかを見つけやすいです。Agentの失敗や訂正の履歴は、大きな資産だと思います。

ただし、保存した履歴の量が増えただけで、それがそのまま次の仕事で使える能力になるわけではありません。履歴には優れた判断だけでなく、偶然の成功、古い前提、その場限りの回避策も混ざっています。現在の実装や業務結果と照らして裏を取り、残すべき判断を選別して初めて、履歴を再利用できる形へ変えられます。

候補を見つけたら、現在のコードとGitを確認します。モデルやCLIの更新に関係する内容なら、現行ドキュメントと実際の挙動も確かめます。過去には正しかった回避策が、いまも必要とは限らないからです。

CodexとClaude Codeは別々に調べてから重ねる

最初から二つの履歴を一つにまとめると、共通する反復は見つけやすくても、どちらか一方にだけ必要な設定や操作を見落とします。

別々に抽出した後で、同じ仕事・入力・完了条件に対応する判断を、共通核として重ねます。片方にしか現れない反復は捨てず、CodexまたはClaude Codeで違う部分として残します。

採用しなかった案も評価ケースになる

履歴から残すのは、最終的に採用した回答だけではありません。

実際に記事制作の手順を見直したときは、レビューで出た指摘をそのまま採用せず、現在の実装と照らし合わせました。たとえば、下書きをdraft: trueで表す案は、このリポジトリがpublished: falseを使うため採用していません。一方で、現在の契約に合う指摘は手順へ反映しました。正しい例だけを残すと、もっともらしい別の書き方へ戻る失敗を見逃すからです。

会話には、その場限りの事情や秘密情報、たまたま成功した手順も含まれるため、Skillへ貼り付ける前に選別します。何を採用し、何を拒否したのかを、理由とともに小さなケースに変えます。

履歴から見つけた内容は置き場所を分ける

残す価値がある内容は、Rules・Skill・scripts・評価ケースなどに分かれます。

履歴から規則を抽出しただけでは、資産化としてはまだ半分です。すべてを自然言語のSkillへ集約しようとせず、学びの性質に合った置き場所を選びます。そのうえで、同じ失敗が将来の改訂で再発しないように、秘密情報や一度限りの事情を取り除き、修正前には失敗し、修正後には合格する回帰ケースとして残します。

最初は全履歴を見て運用後は差分を見直す

最初の一回は、CodexとClaude Codeの全履歴を対象にします。最近の会話だけでは、以前から繰り返している訂正や、すでにSkillへ反映した理由を見落とすためです。

毎回すべてを読み直す必要はありません。初回監査の日付または最後に確認したイベントを記録し、以後はそこからの差分を見ます。新しい訂正、手動での介入、回帰ケースの再発、モデルやCLIの更新があったときは、該当するSkillと周辺のRuleを見直します。全体を再監査するのは、大きなモデル更新や責務構成の変更があったときでよいと思います。

安定させたい仕事からファイル構成を決める

Skillを作る前に、私は次の四点を決めておきたいです。

1. 誰のどの反復作業を安定させるのか
2. CodexやClaude Codeなど、どのAIエージェントで動かすのか
3. 説明だけで足りるのか、参照資料・テンプレート・実行コードが必要か
4. 成功をどう測るのか

一度しか行わない簡単な依頼や、一行で説明できる恒常的な規則は、無理にSkillにしなくてもよいと思います。常に効かせたい方針はRules、入力を整えるだけならプロンプトの雛形、一つの操作はToolの持ち場です。

Skillが効くのは、手順・分岐・検証・再試行を含む仕事です。

たとえば、デプロイ、リリース検証、記事の公開前監査、定型レポートの作成。判断する順番と合格条件まで再利用したい仕事が候補になります。

Skillを増やすこと自体を目的にすると、似たdescriptionが競合し、どれを使うべきか判断しづらくなります。まずは一業務です。

失敗したときの影響で自由度を変える

Skill本文をどこまで細かく指定するかは、仕事の失敗コストで変えます。

自由度を下げるほど品質が上がるとは限りません。文章やデザインのように正しい経路が一つではない仕事は、成果物の評価軸を固定し、作り方には余地を残します。反対に、削除対象や送信先の確認は安全境界なので固定します。

Skillは共通仕様とAIエージェントごとの違いを分けて考える

Agent Skillsの仕様では、SkillはSKILL.mdを必須とするディレクトリです。scripts/・references/・assets/は任意で、ほかのディレクトリを置くこともできます。

my-skill/
├── SKILL.md
├── scripts/
│   └── validate.py
├── references/
│   └── domain-rules.md
├── assets/
│   └── report-template.md
├── evals/
│   └── evals.json              # 評価ガイドとAnthropicのSkill Creatorが使う任意ディレクトリ
└── agents/
    └── openai.yaml             # OpenAI向けの任意拡張

ここで分けたいのが、Agent Skillsの共通仕様と、それを利用するAIエージェント側の仕組みです。

OpenAIのSkill作成ドキュメントも、SkillはオープンなAgent Skills仕様を土台にしていると説明しています。agents/openai.yamlは、その共通仕様にChatGPTとCodex向けの表示・連携情報を足すファイルです。

「業界標準」と言い切るより、複数のAIエージェントが採用しているオープン仕様と表現する方が正確です。一方、agents/openai.yamlやevals/は共通仕様の範囲外です。

ChatGPTに作ってもらったらアイコンまで用意されて驚いた

最近、ChatGPTにSkillを作ってもらったところ、SKILL.mdだけではなくアイコンまで用意してくれて、ちょっとびっくりしました！

アイコンはassets/に置かれ、OpenAI向けのagents/openai.yamlから参照されます。

interface:
  display_name: "API Change Review"
  short_description: "Review API compatibility and migration risk"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#2563EB"

ChatGPTやCodexの画面では、Skill名と説明に加えて、こうした表示情報も使えます。Skill Creatorは用途を聞きながら、必要に応じて本文・補助ファイル・表示用の素材まで一つのSkillとして揃えてくれます。

ただし、アイコンがSkillの本体ではありません。Claude CodeやGemini CLIがagents/openai.yamlを使わなくても、SKILL.mdだけで主要な手順を実行できる構成にしておきます。アイコンやMCP依存など、OpenAIだけで使う情報を共通のSKILL.mdに混ぜないことが大切です。

SKILL.mdの基本形式は共有できます。一方で、どこから探索するか、明示起動をどう扱うか、追加メタデータをどこに置くかはAIエージェントごとに違います。

複数のAIエージェントへ配布するなら、共通核を一つ決め、AIエージェントごとの差分を別ファイルまたは生成処理に寄せた方が管理しやすいです。すべての拡張項目を一つのfrontmatterに詰め込むと、Codexでは受理されても、Claude Codeでは同じ意味にならないといった差が起こり得ます。

私なら共通核を小さく保つ

移植性を重要視する場合、共通のfrontmatterはnameとdescriptionに絞ります。

---
name: reviewing-api-changes
description: Reviews API changes for compatibility and migration impact. Use when reviewing API diffs, schemas, pull requests, or version upgrades.
---

# Reviewing API Changes

Follow the workflow below.

Agent Skills仕様にはlicense・compatibility・metadata・実験的なallowed-toolsもあります。ただし、対応状況はAIエージェントごとに確認が必要です。共通部分を最小にしておくと、特定のAIエージェントだけの都合で、共有する原本の設計まで歪めずに済みます。

SKILL.mdはルーターと手順書の二つの顔を持つ

SKILL.mdはYAML frontmatterとMarkdown本文で構成します。

frontmatterはSkillを見つけるための情報で、本文は起動後に実行する手順です。この二つは役割が違います。

Skill全体の使い方は、二つに限りません。手順を実行する「手順書」、条件に合う資料だけを読む「参考書」、利用者が名前を指定して起動する「カスタムコマンド」という三つの使い方が重なります。

Claude CodeのSkillドキュメントでは、Skillを/skill-nameで明示起動でき、従来のカスタムslash commandとSkillが統合されています。これはClaude Code固有の利用方法です。Agent Skillsの共通仕様は、すべてのAIエージェントに同じコマンド名や引数展開を求めていません。

nameは機械的に検証できる

Agent Skills仕様のname要件は明確です。

• 1〜64文字
• Unicodeの小文字の英数字とハイフンを使う
• 先頭と末尾をハイフンにしない
• 連続ハイフンを使わない
• 親ディレクトリ名と一致させる

この記事では、複数のAIエージェントへの移植性を考え、Skill名をASCIIの小文字・数字・ハイフンに限定します。共通仕様が許す名前のうち、この記事で採用する範囲を示した命名方針です。 次の正規表現は、その文字種とハイフンの位置を確認するものです。1〜64文字であることと、親ディレクトリ名との一致は別に検証します。

^[a-z0-9]+(-[a-z0-9]+)*$

helperやutilsのような名前より、reviewing-api-changesのように仕事が見える名前の方が一覧から判断しやすいです。

descriptionには起動条件を書く

descriptionには「何をするか」と「いつ使うか」の両方を書きます。共通仕様の長さは1〜1,024文字です。本文にだけ起動条件を書いても、本文を読むかどうかの判断には使えません。

Agent Skillsのdescription設計ガイドも、狭すぎる説明は必要な場面で起動せず、広すぎる説明は不要な場面で起動すると説明しています。

私は次の形から始めます。

[行う処理]。[対象・形式・主要機能]。Use when [具体的な依頼・文脈・語句]。

悪い例は、仕事も起動場面も分からない説明です。

description: Helps with APIs.

改善すると、対象と判断軸が見えるようになります。

description: Reviews REST and GraphQL API changes for backward compatibility, authentication risk, and migration impact. Use when reviewing API diffs, OpenAPI schemas, pull requests, endpoint changes, or version upgrades.

文章として格好をよくするより、実際の依頼で使われる語を前半に置く方が大切です。

descriptionはSkill一覧全体で設計する

プロジェクト固有のSkillを増やしていくとき、私はSkill単体ではなく、利用可能なSkill一覧全体でdescriptionを設計することが特に重要だと考えています。

一つずつ読めば正しいdescriptionでも、一覧に並べると対象範囲が重なっていることがあります。 その結果、関係のないSkillが呼ばれる、必要なSkillが呼ばれない、似た別のSkillが選ばれる、といったことが起こります。

OpenAIのSkill作成ドキュメントでも、暗黙起動は依頼とdescriptionの一致で決まり、対象範囲と境界を簡潔に書くよう案内されています。 CodexではSkillが増えると、最初に見せる一覧のdescriptionが短縮され、一部のSkillが省略される場合もあります。個々の説明だけでなく、一覧に並んだときに区別できるよう設計する必要があります。

たとえば、次のようなSkillが同じプロジェクトに並んでいる状態です。

exporting-csv
creating-csv
formatting-csv
validating-csv

すべてのdescriptionに「CSV出力」と書かれていれば、AIエージェントがどのSkillを選ぶかが不安定になります。 私はここでSSOT（Single Source of Truth、信頼できる情報源を一つに定める考え方）を強く意識しています。 同じ目的の依頼を受ける入口を複数のSkillに分散させず、一つのSkillに集約します。 実際に、チームで運用しているプロジェクトでは週に一度、Skillを含む基盤全体を改訂しています。Skillの数も多いため、このあたりは全体の関係を見ながら慎重に調整しています。

ただし、CSVという共通点だけで、すべてを一つにはまとめません。

exporting-accounting-records
analyzing-survey-results
importing-customer-data

CSVは入出力形式であり、この三つは仕事の目的が違います。 まとめる単位は、利用者の目的・必要な入力・判断の流れ・成果物と完了条件・操作できる範囲・確認が必要な場面が共通する一つの手順・知識です。

たとえば、給与計算の結果から会計ソフトへ取り込む仕訳CSVを作る仕事です。取込先がfreee会計かマネーフォワード クラウド会計かでCSVの仕様は変わっても、利用者がしたいことと作業の流れは変わりません。この場合は入口となるSkillを一つにし、SKILL.mdから取込先ごとのreferences/へ振り分けます。

## Routing

- 取込先がfreee会計なら `references/freee-accounting-csv.md` を読む
- 取込先がマネーフォワード クラウド会計なら `references/money-forward-accounting-csv.md` を読む
- 入力ファイルの文字コードを変換する場合は `references/encoding.md` も読む
- 取込先を判断できなければ推測せず確認する

この例でdescriptionに書くのは、給与計算の結果から会計ソフト取込用の仕訳CSVを作る仕事までです。freee会計とマネーフォワード クラウド会計の詳しいCSV仕様まで詰め込みません。仕事の入口はdescriptionに書き、取込先の振り分けをSKILL.md、各CSV仕様をreferences/に分けます。同じ仕様を何度も書かないため、変更時に直す場所が分かりやすく、誤ったSkillが呼ばれる可能性も減らせます。

プロジェクトにSkillを追加するときは、新しいdescriptionだけを見るのでは足りません。既存Skillのnameとdescriptionを一覧にし、同じ依頼が複数のSkillに該当しないか、隣接する依頼を奪っていないかまで確認します。

Skillは必要なときだけ開く参考書にもなる

私はSkillを、作業手順だけでなく、必要なときにドメイン知識を呼び込む参考書としても使っています。

常駐ルールや最初のプロンプトに大量の専門知識を入れると、その作業では使わない情報までコンテキストに入ります。今の判断に関係しない情報まで増やすと、かえってノイズになります。

Skillなら、最初に読み込まれるのはnameとdescriptionです。依頼がdescriptionと合ったときにSKILL.mdが読み込まれ、さらに必要になった資料だけをreferences/などから参照できます。必要になった瞬間に、その仕事の参考書が手元へ来る。これは非常に素晴らしい仕組みだと思っています。

Agent Skills仕様のProgressive disclosureは、この順序をメタデータ、指示、必要な資産の三段階として定めています。OpenAIのスキル作成ドキュメントも、CodexはSkillを使うと判断した時点でSKILL.mdの指示全文を読み込むと説明しています。

ここで、「リポジトリに資料が存在すること」と「資料本文がモデルのコンテキストへ入ること」は別です。references/や一般的なdocs/に資料を置くだけでは、本文はモデルのコンテキストへ自動投入されません。docs/は人やAIエージェントが探索して読む知識の置き場にはできますが、Agent Skills仕様の標準ディレクトリではありません。このリポジトリではdocs/ツリーを廃止しているため、プロジェクト固有の推奨配置としても使いません。

読み込む情報が増える順序を図にすると、次の三段階になります。

図の右端へ進むのは、起動後の手順が参照条件に該当した場合だけです。Skillを選ぶ前にSKILL.mdと詳細資料をすべて読み込む構成は避けます。また、補助資料へリンクするだけで必ず読まれるとも限りません。Claude Codeのcontext window解説でも、2026年9月3日時点では起動前にSkillの説明が入り、Skill本文は実際に起動したときに入ると説明されています。

ただし、特定の単語が含まれていれば必ず起動する、という単純な仕組みではありません。依頼とdescriptionの意味をAIエージェントが照合して判断します。そのため、利用者が実際に使う言い回し、対象となるファイル、関連する作業をdescriptionに書いておくことが大切です。必ず起動させたい場面では、自動起動だけに任せずSkill名を明示します。

一方、すべての作業で必ず守る安全規則や禁止事項は、必要なときだけ呼ばれるSkillに預けるべきではありません。常時適用するルールはAGENTS.mdやCLAUDE.mdなどに置き、特定の仕事で必要になる専門知識はSkillから呼び込む。この分け方が扱いやすいと考えています。

本文には判断と順序を書く

本文に置くのは、エージェントがその仕事を完了するための情報です。

1. 目的と完了条件
2. 必要な入力と不足時の処理
3. 判断分岐
4. 順序付きの作業手順
5. 参照ファイルを読む条件
6. スクリプトを実行する条件
7. 出力形式
8. 検証と再試行
9. 停止・確認・拒否の条件

必要な入力が依頼文になければ、許可された既知の取得元から解決できるか確認します。そこで解決できない場合に、結果を左右する不足情報を質問します。差分や設定を取得できるのに、利用者へ再提出を求めて止まらないようにします。 検証を終える条件も必要です。変更に対応する必須検証が通ったら成果物の完成へ進み、追加の変更・新しい失敗・未解決の懸念がない限り、同じ検証の反復や対象範囲の拡大は行いません。

逆に、一般知識や大量のAPI仕様、更新のたびに変わる情報を本文に抱え込む必要はありません。

Agent Skills仕様は、SKILL.mdを500行未満に保ち、詳細な資料を別ファイルに分けることを推奨しています。 500行は合否を決める魔法の数字ではありません。ただ、Skillが起動すると本文全体が読み込まれるため、本文を短く保つ設計上の理由はあります。

scriptsとreferencesとassetsにはそれぞれ別の役割がある

すべてをMarkdown本文に書くと、読む量が増えるだけでなく、同じ入力から同じ結果を出したい処理までモデルの解釈に委ねることになります。

この役割分担を、実行時の流れとパッケージ境界として重ねると次のようになります。SKILL.mdを判断と手順の中心に置き、必要な資産と実行能力へつなぐ構成です。

図の読み方

1. 依頼はdescriptionの仕事と起動条件に照合され、必要な場合だけSkillを開きます。
2. SKILL.mdは判断・分岐・順序・検証・停止条件を統括します。
3. 詳細知識はreferencesに、同じ入力から同じ結果を出す処理はscriptsに、成果物の素材はassetsに分けます。
4. 常時規則はRulesに、単一能力や接続はToolまたはMCPに、イベント処理はHookに残します。Hookの失敗時に操作を止めるかは別途確認します。

Source

本記事の責務分担

Method

本文で説明した配置原則を構造化

図の中央に置いたSKILL.mdには仕事の進め方をまとめ、条件に応じて専門知識・同じ入力から同じ結果を出す処理・成果物素材・外部能力を呼び分けます。

scriptsには同じ入力から同じ結果を出したい処理を置く

ファイル形式の検証、値の抽出、定型変換、成果物の機械検査はscripts/に寄せやすい処理です。

ただ実行できるだけでは足りません。スクリプトには次の性質を持たせたいです。

• --helpで用途・入力・出力・終了コードが分かる
• 成功時と失敗時の出力が区別できる
• 部分的な成果物を成功として扱わない
• 外部への副作用がある場合は、外部の状態を変えずに結果を確認できるdry-runを用意する
• 失敗後に再実行しても状態を壊しにくい

モデルが毎回同じ検証コードを生成するより、レビュー済みのスクリプトを再利用する方が、結果の比較もしやすくなります。

referencesは必要なときにだけ読む

references/には、ドメイン規約、出力スキーマ、長いAPI仕様、例外一覧を置きます。

重要なのは、SKILL.mdを条件付きの索引にすることです。ファイル名だけを並べたり、「詳しくはreferences/を参照する」と一括で指示したりせず、何が書かれていて、どの条件で読むのかを一行ずつ対応させます。

- API schema changes are in scope: read [references/api-compatibility.md](references/api-compatibility.md).
- Authentication changes are present: read [references/auth-boundaries.md](references/auth-boundaries.md).

Agent Skills仕様のFile referencesは、参照をSKILL.mdから一段の深さに保ち、深く入れ子になった参照チェーンを避けるよう推奨しています。これは二階層以上を禁止する要件ではありません。補助資料も必要時に読み込まれるため、リンクの存在だけで読まれることを保証するものではありません。

私の過去の利用環境では、参照先からさらに別の資料へ案内する二階層以上の構成で、奥の資料が読まれないことがありました。ただし、当時の製品名・version・起動条件を再現できる記録が残っていません。このローカル観測を一般仕様の証拠には使わず、現在は仕様の推奨どおりSKILL.mdから必要な資料へ一段で到達できる構成を選んでいます。

assetsには成果物に使う素材を置く

レポートの雛形、文書テンプレート、画像、フォント、サンプル設定など、成果物にコピーしたり変換したりして使うものがassets/です。

テンプレートに判断規則まで書くと、手順を変えるたびにSKILL.mdとテンプレートの両方を直す必要があり、片方だけ古いまま残りやすくなります。assets/には、選ばれた後にコピーまたは変換する素材だけを置きます。

動作条件と上限もSkillの契約にする

スクリプトが正しくても、必要なruntimeや認証情報がない環境では動きません。Skillの再現性には、手順だけでなく動作条件も含まれます。

• 必要なコマンド、runtime、package managerと対応version
• 対応するOS、shell、作業ディレクトリ
• 必要な環境変数の名前と、値をどこから渡すか
• network接続、認証、MCP serverなど外部依存
• timeout、入力件数、ファイルサイズ、出力先の上限
• 依存が足りないときに停止する条件と確認方法

秘密情報の値そのものはSkillへ書きません。必要な変数名と取得方法だけを示し、実行前に存在を確認します。compatibilityへ説明を書いても実行環境は揃わないため、検証スクリプトで確かめます。

作成は最小の初稿と評価ケースから始める

最初から完全なSkillを書くより、Skillなしで失敗を観察してから、必要な規則だけを足した方が因果を追いやすいです。

私なら次の順序で作ります。

1. 目的を一文で定義する
2. 実際の依頼例を集める
3. Skillなしで実行し、失敗を記録する
4. 対象範囲と起動条件を決める
5. 再利用資産をscripts/・references/・assets/に分類する
6. 最小のSKILL.mdを書く
7. 同じ入力から同じ結果を出したい処理をスクリプト化する
8. frontmatterとファイル参照を静的検証する
9. 新しい会話やコンテキストで動作を確認する
10. Skillなしと旧版を同じ課題で比較する
11. 実際の失敗を回帰ケースに追加する
12. 案件だけの情報を一般化してから配布する

Skill Creatorの守備範囲は、AIエージェントごとに違います。Codexの$skill-creatorは、Skillの目的、起動条件、スクリプトの要否を聞き取り、SKILL.mdと補助ファイルの初稿を作ります。現行のSKILL.mdと同梱スクリプトには、評価ケースを実行して比較する手順は含まれていません。Anthropicが公開するSkill Creatorは、初稿に加えて、評価ケースの作成、Skillなしや旧版との比較、採点、集計、descriptionの調整まで自動化します。

ただし、Creatorに「良いSkillを作って」とだけ頼むより、先に履歴から実際の失敗・訂正・採否を渡す方が、対象範囲と評価ケースを具体化できます。私なら、まず履歴から候補を見つけます。次にSkill Creatorで雛形を作り、対応する環境では反復評価まで進めます。

Claude Codeで21個のSkillを運用し、うち16個を自作した記事でも、繰り返す指示をSkillへ切り出し、Skill Creatorで評価と改善を回す流れが紹介されています。私は、実際の反復から作り、評価を返して直すところを参考にしています。

私がここへ足したいのは、その一つ前です。自分では繰り返しだと気づいていない訂正まで、CodexとClaude Codeの履歴から見つけます。

最低でも、正常系・境界条件・対象外の三件は用意したいです。

次は管理例です。Agent Skills仕様は評価の形式を定めていません。Agent Skillsの評価ガイドは成果の評価をevals/evals.json、description最適化ガイドは起動の評価をshould_trigger付きの問い合わせ一覧として別々に扱いますが、ここでは三件を一覧できるよう一つにまとめています。

[
  {
    "id": "normal-review",
    "should_trigger": true,
    "prompt": "Review this API schema change",
    "assertions": ["compatibility finding", "evidence", "required action"]
  },
  {
    "id": "missing-input",
    "should_trigger": true,
    "prompt": "Review the API change; the diff is not attached",
    "assertions": ["retrieve evidence from known authorized sources when available", "ask only if necessary evidence cannot be obtained", "do not invent a change"]
  },
  {
    "id": "out-of-scope",
    "should_trigger": false,
    "prompt": "Write a product announcement",
    "assertions": ["skill should not trigger"]
  }
]

対象外のケースも入れるのは、起動すべき場面と避けるべき場面を見分けられるかどうかが、descriptionの品質を左右するからです。対象範囲が近いSkillも同時に利用できる状態で、どれが選ばれるかを確認します。

Agent Skillsの評価は起動と成果を同じ条件で比べる

Skillのevalは、SKILL.mdの出来を点数化することではありません。新しい会話で同じ仕事を繰り返し、使うべき場面だけで起動して、許可された範囲で必要な確認を行ったうえで、期待する成果をSkillなしや旧版より安定して再現できるかを確かめます。Skillが選ばれ、判断し、Toolを動かし、成果を返す一連の契約を、同じ条件の比較と実動作のテストで検証する作業です。

Task・Trial・Grader・Outcomeなど、AI Agent評価全体の用語と運用はAI Agent評価の技術ガイドで整理しています。この記事で扱うのは、Agent Skillsに固有の起動条件と、Skillを変更した効果の測り方です。

Agent Skillsのオープン仕様が定めるのは、Skillを配布する形式です。評価ケースや採点処理の形式は仕様の範囲外で、任意ディレクトリの一覧にもevals/は挙がっていません。ただし、Agent Skillsの評価ガイドとAnthropicのSkill Creatorは、手書きの評価ケースをSkill内のevals/evals.jsonに置き、実行結果と集計はSkillの隣のワークスペースへ分ける規約を採っています。Claude CodeのSkillドキュメントも同じ配置を案内しています。OpenAIのCodex向けドキュメントは、評価ケースの置き場所を定めていません。

一度うまく動いた、という感触だけでは改善を判断できません。

評価の全体像は、候補版だけを採点する直線ではありません。実際の失敗をケース化し、同じ条件で三者を比較し、判定結果を次の回帰ケースへ戻すループです。

図の読み方

1. 実際の失敗と人の訂正から、秘密情報と一度限りの事情を除いて評価ケースを作ります。
2. Skillを直す前に、合格条件と禁止条件を固定します。
3. 同じモデル・Tool・入力・実行環境で、Skillなし・旧版・候補版を比較します。
4. 機械判定と人の判断を組み合わせ、重大な安全違反は一件でも不合格にします。
5. 失敗の種類を回帰ケースへ戻し、新しい会話でも再現できるまで改訂します。

Source

本記事の評価手順

Method

比較条件と回帰ループを構造化

図の上段にある比較条件が揃って初めて、候補版による差を読めます。右下の分岐は、外部送信や削除などの重大な安全違反を、ほかの評価項目の平均点で埋めないことを示しています。

起動が正しくても、成果が期待と違えば失敗です。最終回答が自然でも、必要なファイルが作られていない、誤った対象を更新した、確認前に外部へ送信したのであれば合格にはできません。Skillの評価では、実行前の起動と実行後の成果を分けて見ます。

判断と実動作も分けます。Skillが正しい操作を選んだかと、ToolやCLIがその操作を契約どおり実行したかは、別の問いだからです。

私のdotfilesにあるsearching-agent-historyでは、Skillが履歴検索CLIのagent-historyに--projectを付けたcommandを選んでも、CLI側が対象外のsession本文を読んでいれば失敗です。そのため、起動とcommandの選択はdry-runで採点処理のgraderが判定し、対象外のsession本文を走査しないことはCLI側の受け入れテストで確認しています。どちらをどの方法で証明したかは、benchmarkに残します。

Skillの成功と業務の成功を分ける

Skillの評価が高くても、その仕事が顧客や現場にとって良い結果を生んだとは限りません。たとえばAPIレビューSkillが互換性の問題を正確に指摘しても、改修前に担当チームへ届かず障害を防げなければ、業務として成功したとは言えません。

私は評価を次の三層に分けて考えます。

1層目の「Skillの評価」は、本記事でも詳しく掘り下げて扱える技術的な領域です。しかし、2層目（業務の評価）や3層目（組織の評価）は、対象業務の責任者や現場の判断なしには決められません。公開ベンチマークや一般的な文章品質だけで採点するのではなく、自分たちの仕事において何を成功とするかをあらかじめ定義しておく必要があります。

さらに、改善を続ける過程では「Skillをどう直すか」だけでなく、「そもそもこの業務をSkillで改善し続けるべきなのか」「評価基準そのものが妥当か」も見直します。たとえば問い合わせ対応のSkillをどれだけ磨いても、問い合わせの原因が製品UIにあるなら、直すべき対象はSkillではなく製品そのものかもしれません。やり方（手段）を改善する循環と、目的や評価基準そのものを問い直す循環は、切り離して回す必要があります。

比較対象はSkillなしと旧版の二つ

比較条件は、同じモデル・同じTool・同じ入力・同じ実行環境に揃えます。作成中の会話には目的や訂正が残っているため、各実行は新しい会話または初期化したコンテキストから始めます。

• Skillなしとの比較では、そのSkillを加える価値があったかを見る
• 旧版との比較では、今回の変更で既存の成功を壊していないかを見る

候補版だけを実行しても、もともとSkillなしで解ける課題だったのか、旧版より良くなったのかは分かりません。Agent Skillsの評価ガイドでも、最初は二〜三件の現実的なケースを用意し、SkillありとSkillなしを新しいコンテキストで比較する流れになっています。

Skillなし・旧版・候補版では、対象Skillの有無または版だけを変えます。Rulesやuser configを無効化する場合も、三条件で揃えます。隔離した環境での結果を、そのまま実運用の設定下での効果とは扱いません。

新しい会話でも、前の試行のファイルやキャッシュが残ることはあります。評価ガイドに沿って、コンテキストと実行環境を別々に初期化します。対象Skillが探索先に残る場合は、「使わない」と指示した比較として記録し、利用できない環境での比較と区別します。

searching-agent-historyの評価では、Codex CLI 0.150.1を使い、試行ごとに新しいコンテキストと読み取り専用のsandboxで実行しました。Skillなしの条件はuser configとrulesを無効化してpromptで指示し、探索先を物理的に分離していないという限界をbenchmarkに書いています。この記述だけでは、三条件で設定が揃っていたかまでは確認できません。Skill単独の効果を判断するには、runnerと各試行の設定記録も照合する必要があります。

何が効いたかは盲検比較とアブレーションで確かめる

文章やデザインなど、人の判断が残る評価では、可能なら候補版と比較対象の名前を伏せます。どちらが新しいSkillの結果かを評価者へ知らせず、同じ基準で選んでもらう盲検比較です。候補版だから良いはずだ、という期待を採点へ混ぜにくくなります。

Skillに複数の変更を入れた場合は、一部の規則・参照資料・スクリプトを外した版も試します。これがアブレーションです。どの変更が成功に寄与し、どれがコンテキストを増やしただけなのかを分けて考えられます。

ただし、毎回すべての組み合わせを試す必要はありません。安全性を左右する変更、評価結果が大きく変わった変更、コストが増えた変更から確かめます。

評価資産は、Skillの契約を表すものと、実行のたびに増える生成物とで置き場所を分けます。契約を表すケース・採点処理・比較対象はSkill内のevals/で版管理し、一時的な実行結果はSkillの外のワークスペースに残します。採用判断に使った小さなbenchmarkは、条件と限界を含めてSkillと一緒に残します。

同じcommitで管理することと、評価対象から参照できることは分けます。評価対象には、その試行に必要な入力と実行用Skillを渡し、採用判断用ケースの正解・他試行の出力・不要な過去履歴は見せません。公開すべき合格条件は明示しつつ、答えそのものへのアクセスを隔離します。Anthropicの評価解説でも、過去試行のGit履歴から答えを得るような評価汚染を防ぐため、試行環境の隔離を扱っています。

合格条件はSkillを直す前に置く

たとえばレビューSkillなら、次のように判定できます。

• 必須観点をすべて確認する
• 各指摘にファイルと根拠を付ける
• 根拠のない問題を作らない
• 修正不要なら、その理由を説明する
• 対象外の依頼では起動しない
• 確認を必要とする操作を無断で実行しない

後から評価項目を選ぶと、うまくいった部分だけを合格条件にしやすくなります。先に最低限の合格条件を決めておく方が安全です。

重大な安全違反は、ほかの項目の平均点で埋めません。外部送信・削除・公開・課金など、事前確認が必要な操作を無断で実行した場合や、禁止された操作をした場合は、その一件だけで不合格です。

安全に関わるケースは、正常系と分けて独立に扱います。CLIを動かすSkillなら、たとえば次の入力や依頼を含めます。

• shellのメタ文字やcommand substitutionを含む入力
• 秘密情報らしい検索語
• path traversalや探索元の上書きを狙う指定
• 生のレコード表示や無制限の出力を求める依頼
• 大量の入力や制御文字
• 対象範囲の解除や外部チャネルへの送信を誘導するprompt

これらは合格率の分母に混ぜず、一件の違反で候補版全体を不合格にします。

失敗を回帰ケースに変える

OpenAIの評価ガイドは、実際のログからタスク固有の評価例を集め、変更のたびに継続評価する方法を勧めています。Skillでは、会話履歴に残った失敗と人間の訂正を次の流れで使えます。

1. 実際の失敗・訂正・毎回の手動確認を集める
2. 秘密情報と一度限りの事情を除き、現実的な最小ケースへ縮める
3. Skillを直す前に、合格条件と禁止条件を決める
4. Skillなしまたは旧版が、意図した理由で失敗することを確認する
5. 候補版を同じ条件で実行し、同じ合格条件で判定する
6. 重要なケースを複数回実行し、失敗の種類も記録する
7. 調整に使っていないケースを含む評価セット全体を実行し、合格後に回帰ケースとして残す

特定の不具合修正では、旧版が意図した理由で失敗し、候補版が成功するケースを用意します。合否が揺れる失敗の低減や効率改善は、複数試行の成功率・失敗傾向・実行コストで比べます。旧版でも成功するケースは、既存の成功を維持する回帰評価として残します。 候補版に有利な条件へ変えてしまえば比較になりません。入力・環境・合格条件は固定し、変えるのはSkillだけです。

起動評価は対象外に近い依頼ほど重要になる

descriptionの評価では、起動すべき依頼と起動してはいけない依頼を同じくらいの件数で用意します。明らかに無関係な依頼に加えて、同じファイル形式を扱う別目的の作業、似た名前のSkill、Skill名を使わない自然な依頼を含めます。

本来起動すべき依頼をどこまで拾えたかは再現率、実際に起動した依頼のうち正しかった割合は適合率です。読み取りだけで外部の状態を変えない補助Skillでは、取りこぼしを減らす方を優先できる場合もあります。一方、公開・削除・課金につながるSkillでは、誤起動を減らすことと明示確認を優先します。

Agent Skillsのdescription最適化ガイドでは、調整段階で起動すべき例と対象外の例を合わせて約20件用意し、それぞれを複数回試します。調整用と検証用は60対40に分け、採用判断は検証用の例で行う構成です。最初はこの記事で挙げた三件から始め、境界が見つかるたびに増やせばよいと思います。

起動評価では、次のように対象と隣接領域を対にして並べます。

機械判定と人の判断を分ける

ファイルの有無、JSON Schema、テスト結果、Tool引数、禁止操作は、スクリプトで機械的に判定できます。確かめるたびに答えが変わっては困る条件を、毎回モデルの感想に委ねる必要はありません。

一方、文章の分かりやすさ、優先順位、書き手らしさ、デザインの使いやすさは、一致判定だけでは測れません。評価用のモデルを使う場合も、判断基準と根拠を残し、人間の評価と定期的に照合します。私なら、成果物の有無や形式、操作が許可された範囲に収まったか、必要な確認を行ったかは、まず機械で判定します。文章の分かりやすさなど、主観が残る部分を人間または評価用モデルで見ます。

また、正しい成果へ至る経路が複数ある仕事では、Toolの順番を一つに固定しすぎない方がよいです。必須の確認と禁止操作は評価しつつ、最終的な成果を重く見ます。AnthropicのAgent評価の解説も、実行経路を必要以上に固定せず、成果と守るべき手順を分けて採点する考え方を示しています。

判定方法ごとの持ち場を分けると、評価結果の根拠も残しやすくなります。

graderそのものも評価の対象です。壊れたgraderは、壊れたSkillを安全に見せてしまいます。

• graderが合格させるべき例と、拒否すべき反例を用意する
• 候補版だけでなく、graderの偽陽性と偽陰性を確認する
• grader修正前の誤判定を回帰用のfixtureとして残す
• graderを変えたら、過去の結果を再採点する

実際に、searching-agent-historyの初版graderは対象範囲だけを見ていたため、agent-historyをshell経由で呼び出す不正なcommandを合格させました。最初の評価結果は破棄し、commandの形と未対応optionの拒否をgraderへ加えてから、評価をやり直しています。

一度の成功と安定した成功を分ける

Agentの出力には揺らぎがあります。一度でも成功できることと、新しい会話で繰り返しても重大な失敗を起こさないことは別です。

重要なケースは複数回実行し、合格率だけでなく、失敗の種類、所要時間、トークン数、Tool呼び出し回数、読み取ったbyte数、外部状態の変更数、確認を求めた回数、graderと人の判定の不一致も記録します。平均値が良くても、確認を飛ばす実行や極端に遅い実行が混じるなら、その理由を調べます。安全性では、平均の成功率より一度の重大違反を重く見ます。

評価ケースを増やすときは、役割を三つに分けます。同じ例を見ながらSkillとgraderを何度も直すと、その文面にだけ効く規則を一般的な改善と取り違えるためです。

採用判断用の未使用ケースでも合格すれば、調整に使った例以外で再現できる根拠が得られます。ただし、結果が支持するのは評価セットが代表する業務と実行条件の範囲です。未知の業務や別モデルでも成功するという保証にはなりません。

一回の実行結果だけでは見えない差を、次の記録で追います。

測定値には母集団と失敗可能性を残す

Skillの評価そのものを公開ベンチマークで証明している事例ではありませんが、Bunのリポジトリには測定と回帰防止の設計として参考になる実装があります。ここでは調査対象をcommit 06820dcへ固定しました。

ここから言えるのは、Bunの開発工程が実測を使い、その運用知識の一部をSkillへ残していることまでです。BunのAgent SkillsがA/Bテストで最適化済みだ、という意味ではありません。観測事実と、Skill評価へ応用する私の判断を分けておきます。

並列化は最初から入れない

Subagentを使えば速くなるように見えても、分割・統合・重複確認にはコストがあります。

最初は直列で実行し、その結果を基準に、遅い工程と各工程の独立性を確認します。複数のケースが互いに独立し、統合後の再検証を含めても所要時間が短くなる場合だけ並列化します。

並列化は、次の条件をすべて確認してから採用します。

• ケース同士が入力や状態を共有せず独立している
• 分割と結果統合の費用を測定へ含めている
• 統合後に評価セット全体を再検証する
• 同じ条件の直列実行より総所要時間が短い

一つでも確認できない場合は直列実行を基準として残します。

速さの主張には、対象ケース・実行環境・試行回数・比較対象が必要です。平均だけでなく、遅い側の結果や最も時間がかかったケースも見ておきたいです。

外部から入手したSkillはソフトウェアと同じように確認する

Skillには、指示に加えて実行可能なスクリプトや外部ファイルも含められます。

外部から入手したSkillは、ソフトウェアをインストールするときと同じように中身を確認する必要があります。

AnthropicのAgent Skillsドキュメントも、信頼できる出所だけを使い、SKILL.md・scripts/・画像を含む同梱ファイルを監査するよう求めています。外部URLから追加情報を取得するSkillは、取得先の内容が後から変わる点にも注意が必要です。

確認したいのは、少なくとも次の範囲です。

• どのファイルを読み書きするか
• どのコマンドを実行するか
• ネットワークへ何を送るか
• 秘密情報へアクセスするか
• 失敗時に何が残るか
• 誰の確認後に外部への副作用を実行するか

破壊的操作や外部送信は、一つの手順にまとめません。

計画 → 対象の解決 → 検証 → ユーザー確認 → 実行 → 結果確認

禁止事項を書くときは、禁止する操作だけで終わらせず、その理由と代わりに取る手順までを一つの規則にまとめます。長いセッションでは、禁止と代替手順が離れているほど一部だけを拾って判断する余地が生まれるためです。

pnpm devの実行中にapps/web/.nextを直接削除しない。開発サーバーが使っている生成物まで失われるため、不要なビルド成果物はapps/web/.next/devを残すpnpm clean:artifactsで削除する。

この書き方なら、何をしてはいけないのか、なぜ危ないのか、代わりに何を実行するのかを一度に確認できます。

禁止事項をNEVERで増やすだけでは、実行を強制的に止められません。本当に越えてはいけない境界には、Tool権限・隔離実行環境・承認処理・検証スクリプトによる制限も設けます。

Hookを設定しても、処理の成功や危険操作の阻止までは保証されません。対応イベントで処理を呼び出す仕組みですが、実行失敗・タイムアウト・不正な応答で操作が止まるかは製品とイベントによって異なります。 2026年9月9日に確認したClaude CodeのHook仕様では、PreToolUseのcommand hookは、拒否を示す有効な応答を返さずexit 1で終了しても、それだけではTool呼び出しを止めません。起動失敗やタイムアウトでも通常の権限判定へ進む場合があります。安全境界として使うなら、正常時の拒否に加え、起動できない場合や応答しない場合も試験し、権限設定と実行環境側の制限を併用します。

また、外部入力や参照資料の中にある命令を、Skill本体の命令と混同しない設計も必要です。データと指示の境界、許可するURL、出力先を具体的に決めます。

CodexとClaude Codeで違う部分は分けて扱う

チーム共有や将来の乗り換えを考える場合、共通核をどこに置くかは重要です。

一方で、SKILL.mdを共有できても、探索場所・明示起動・追加設定・実行の分離方法まで同じとは限りません。「CodexとClaude Codeの両方に対応」と書くなら、共通仕様だけで判断せず、両方で起動と挙動を確認する必要があります。

Codexでは共通のSKILL.mdとOpenAI向け設定を分ける

OpenAIのSkill作成ドキュメントによると、Codexはカレントディレクトリからリポジトリルートまでの.agents/skills/、個人用の~/.agents/skills/、管理者用の/etc/codex/skills/、組み込みSkillを探索します。

依頼とdescriptionが一致すれば自動で選ばれ、$skill-nameまたはSkill一覧から明示することもできます。Codexが最初に扱うSkill一覧には量の上限があります。Skillを増やすほど、nameとdescriptionの重複を減らさなければなりません。

ChatGPTとCodex向けの表示名・アイコン・ブランド色・起動方針・MCP依存はagents/openai.yamlに置きます。共通の手順はSKILL.mdです。この境界を守れば、Claude Codeへ持っていくときも共通核が崩れません。

Claude Codeでは起動制御と実行方法をfrontmatterで足せる

Claude CodeのSkillドキュメントは、プロジェクトの.claude/skills/、個人の~/.claude/skills/、Pluginに含まれるSkillを扱います。

Claude Code向けのfrontmatterには、共通のnameとdescriptionに加えて、次のような設定があります。

これらをAgent Skills全体の共通仕様だと思ってSKILL.mdに入れると、Codexでは同じ意味にならない可能性があります。Claude Codeでだけ必要な起動制御と実行方法として扱います。

2026年9月9日に確認したClaude Codeの仕様では、どちらの付与・制限も次のユーザーメッセージで解除されます。allowed-tools: Read Grepだけで読み取り専用にはなりません。継続的なアクセス制限は、権限設定のdenyルールや実行環境側で設けます。

Claude Codeでは、本文から$ARGUMENTS、$ARGUMENTS[0]、$0、名前付き引数を参照できます。利用可能なSkill一覧では、descriptionとwhen_to_useを合わせた説明の既定の上限は1,536文字で、超過分が切り詰められます。この上限はskillListingMaxDescCharsで変更でき、共通仕様のdescriptionの長さとは別の制限です。詳細な手順を起動情報に詰め込む理由はありません。

Claude Codeには、Skillを読み込む前にコマンドを実行し、その出力を本文へ差し込む動的なコンテキスト挿入もあります。現在の差分を扱うSkillなら、実行時の差分情報を渡せるわけです。ただし、コマンドはSkillの権限で動きます。外部から入手したSkillは、本文だけでなく、動的に実行されるコマンドまで確認しなければなりません。

context: forkは、Skill本文を別コンテキストで実行したいときに使えます。長い調査や独立した作業には向きますが、元の会話にある暗黙の前提は自動では伝わりません。必要な入力と返してほしい成果をSkill側に明示します。

シンボリックリンクは探索ルートと個々のSkillを分けて確認する

このリポジトリでは、.claude/skills/を実体として置き、.agents/skills/からシンボリックリンクで参照しています。

.claude/skills/  # Skillの実体
.agents/skills   # ../.claude/skillsへのシンボリックリンク

Claude Codeには実体の.claude/skills/を読ませ、CodexやGemini CLIには共通探索先の.agents/skills/を読ませる構成です。このリポジトリでは、2026年8月23日時点のCodex CLI 0.149.1でSkillを認識できることを確認しました。Gemini CLIのSkill管理ドキュメントも、プロジェクトの.agents/skills/を.gemini/skills/の別名として案内しています。

Claude Codeの現行ドキュメントは、.claude/skills/の中に置く個々のSkillディレクトリをシンボリックリンクにできると説明しています。一方、探索ルートである.claude/skills/自体を別ディレクトリへの一本のリンクにする構成まで、同じ保証だとは読めません。

実際に、.agents/skills/を実体として.claude/skills/自体をシンボリックリンクにする逆の構成では、過去にClaude CodeでSkillが認識されないことがありました。Claude Codeでもシンボリックリンク配下のSkillが一覧に出ない不具合も報告されています。現行ドキュメントと過去の挙動を分けて考えたうえで、私は.claude/skills/を実体にする方が扱いやすいと考えています。

シンボリックリンクの扱いは、AIエージェントの更新で変わる可能性があります。構成を決めたら、Codexでは利用可能なSkill一覧、Claude Codeでは/の補完候補、Gemini CLIでは/skills listを確認し、実際に一つのSkillを起動してから使います。

配布物に開発資産を詰め込まない

実行結果、測定値、開発メモ、変更履歴までSKILL.mdの隣に積み上げると、実行時に参照する資産と開発用資産の境界が曖昧になります。

公式の規約は、この境界を二段で引いています。手書きの評価ケースはSkill内のevals/に置き、実行のたびに増える結果と集計は隣のワークスペースへ分けます。evals/はSkillと一緒に版管理されるため、Gitやplugin marketplace経由の配布では同梱されます。実際にAnthropicの公式pluginリポジトリには、evals/を含んだまま配布されているSkillがあります。一方、Skill Creatorのパッケージ処理が作る.skillアーカイブでは、Skillルート直下のevals/が除外されます。

repository/
├── .agents/skills/reviewing-api-changes/
│   ├── SKILL.md
│   ├── scripts/
│   ├── references/
│   ├── assets/
│   └── evals/
│       ├── evals.json           # 手書きの評価ケース .skill化では除外
│       └── files/               # ケースが使う入力ファイル
├── reviewing-api-changes-workspace/
│   ├── skill-snapshot/          # 比較する旧版
│   └── iteration-1/
│       ├── eval-normal-review/
│       │   ├── with_skill/
│       │   └── without_skill/
│       └── benchmark.json
└── tools/
    ├── validate-skills.sh
    └── sync-skill-targets.sh

私はここから一歩進めて、Skillの契約を表すevalはすべてSkillと一緒に版管理し、一時的な実行生成物だけを外へ分けます。公式の配置では旧版のsnapshotと集計がワークスペース側ですが、採用判断の根拠になったbaselineと小さなbenchmarkまでSkillと同じcommitに残す方が、Skillを変えたときに何をどの条件で証明したかを追えるからです。

searching-agent-historyのSkillでは、evals/に評価ケース、grader、runner、結果のschema、旧版のbaseline、benchmarkを置き、試行ごとの一時ファイルは一時ディレクトリに作って実行後に削除しています。

Skillに入れるのは、実行に必要な資産と、Skillと一緒に版管理する評価の契約までです。evals/が配布物に入るかは経路で変わり、Git配布では同梱され、.skill化では除外されます。どの経路で配るか、ワークスペースをGitで管理するか、Skillの探索ルートの外に置くかは、先に決めておきます。

Skillは差分履歴と環境更新で育てる

Skillは、一度作れば終わる文書ではありません。ただし、毎回全履歴を読み直し、全文を書き換える必要もありません。

私は初回に全履歴を調べた後、監査した日時または最後のイベントをcheckpointとして残し、そこから先の差分を見ます。月に一度の棚卸しを置きつつ、次の出来事があれば予定を待たずに見直します。

変更時には、Skillのversionまたはcommit、対応を確認したAIエージェントとモデル、評価セットのversion、結果、変更理由を残します。候補版が悪化したときに旧版へ戻せるよう、直前に合格していたcommitも記録します。

使われていないSkillを削除するときは、SKILL.mdだけを見ません。ほかのSkill、Rule、スクリプト、CI、ドキュメントから参照されていないかを確認し、必要なら廃止予定を示してから外します。

所有者は、履歴から新しい失敗を拾い、現行環境で評価し、採用または差し戻しを判断する人です。モデル更新時も全面改訂せず、同じ回帰ケースで差が出た場所だけを直します。

新しいモデルや主要なCLIが登場したときも、まず同じケースで挙動の変化を確かめます。2026年9月9日に確認したOpenAIのGPT-6 Astra向けガイドは、確認質問によって作業が止まる場合、SkillやAGENTS.mdの指示への敏感さ、期待より少ない委譲、小さな変更への広い検証を注意点に挙げています。指示を短くする前に、どの指示でどんな失敗が起きたかを見たいです。

採用前に必要な評価一式は、引き続き揃えて実行します。作業中に理由なく増える再検証とは分けて扱い、Skillなしの基準性能とアブレーションを含む次の手順へ落とします。

1. 現行の回帰ケースを固定する
2. Skillなし・旧版・候補版を、同じモデル・Tool・入力・環境で比較する
3. 新しいモデルが指示なしでも満たせるようになった項目を特定する
4. Rule・Skill・モデルの標準挙動で重複する指示を一群ずつ外す
5. 同じ評価ケースを再実行する
6. 品質・安全性・起動精度を落とさない削除だけを採用する
7. 使用モデル、Skillのcommit、評価結果、削除理由を残す

「新しいモデルなら既存のRuleやSkillは不要だろう」という推測だけでは削りません。Skillなしの基準性能と、一群ずつ外すアブレーションで不要性を確かめます。反対に、差が出なかった箇所まで新モデル向けに書き換える必要もありません。同じ回帰ケースで差が出た箇所だけを改定します。

Skill本文だけを持ち運んでも熟練は残らない

複数のAIエージェントで同じSKILL.mdを読めることは、移植性の入り口にすぎません。Skillの文章だけをコピーしても、「なぜその判断が必要なのか」「何をもって合格としたのか」という文脈が失われてしまえば、現場で培った熟練を再現することはできません。

モデルを変えれば、同じSkillでも解釈やToolの選び方は変わり得ます。移植先では同じ評価ケースを再実行し、必要な差分だけを調整します。単にファイルを所有していることよりも、自分たちで構造を理解し、修正し、評価して運用を続けられることの方が重要です。

また、その運用をAIエージェントだけで完結する閉じた循環にしないことも大切です。現場で訂正を行った人がその判断理由を説明でき、評価基準の見直しに参加し、その改善結果を次の仕事で活かせる状態を保ちます。現場から履歴を集めるだけで人間が考える機会まで奪ってしまえば、Skillは改善されても組織としての判断力は育ちません。

典型的な失敗は規則の不足より責務の混線から起きる

よくある失敗は、命令の強さより、仕事・知識・処理・評価の置き場所が混ざったときに起こります。

こうした失敗は、情報と検証を本来の責務へ移すことで直します。

Skillの完成は再現性で判定する

Skillの完成は、SKILL.mdが置かれた時点ではありません。

• 一つの明確な目的に絞られている
• nameとディレクトリ名が一致している
• descriptionに仕事と起動条件がある
• 本文に入力・分岐・手順・出力・停止条件がある
• 長い資料を一段下のreferences/に分けている
• 同じ入力から同じ結果を出す必要がある処理をscripts/に置いている
• 外部への副作用と事前確認が必要な条件が明示されている
• 正常系・境界条件・対象外の起動と成果を評価している
• Skillなしと旧版を同じ条件で比較している
• 重要なケースを新しいコンテキストで複数回試している
• Skillの判断とToolやCLIの実動作を別々に評価している
• 実際の失敗を回帰ケースに追加している
• 主観的な品質を人間または調整済みの評価用モデルで確認している
• graderが反例を拒否し、偽陽性を残していないことを確認している
• 調整に使っていないケースでも再現できている
• 配布対象の各AIエージェントで起動と挙動を確認している
• Skillの成功と業務の成功を別々に評価している
• 業務や評価基準そのものを見直す条件が決まっている
• 判断理由・評価ケース・安全境界を移植先でも再現できる
• 所有者・更新手順・廃止方法が決まっている

最初の一回は履歴の分析だけを依頼する

今日一つだけ始めるなら、Skill Creatorへすぐ作成を頼むより、AIエージェントにリポジトリの履歴を分析してもらいます。依頼文は次の形から始められます。

このリポジトリに属するCodexとClaude Codeの全履歴を、別々に調べてください。

目的はSkillをすぐ作ることではなく、繰り返している失敗・訂正・判断・手動確認を見つけることです。

条件:
- ユーザーの依頼、訂正、採用、拒否、確認判断を優先する
- systemメッセージ、Tool出力、subagentだけの提案を要件として数えない
- 秘密情報、私事、一度限りの案件情報は出力しない
- 候補は現在のコード、Git、ドキュメント、実際の挙動で裏を取る
- 共通する内容、Codexでだけ必要な内容、Claude Codeでだけ必要な内容を分ける
- 各候補をRule、Skill、reference、script、Hook、評価ケース、一度限りに分類する
- 根拠となる履歴の時期と、繰り返した回数または代表例を示す
- この段階ではファイルを変更しない

最後に、優先度、期待する効果、失敗したときの影響、最初に作る評価ケースを提案してください。

この結果を人が確認し、最初の一業務を選んでから、Skill Creatorまたは手作業で最小の初稿を作ります。

最初から複数のAIエージェントへの対応や、大規模配布まで進めなくてもよいと思います。

まずは測定可能な一業務に絞る。Skillなしの結果と比較し、必要な手順だけを加えて改善することを確認する。その後に、必要な処理をスクリプト化し、操作できる範囲と確認手順を固め、配布先を広げる。

この順序なら、仕事の再現性が上がったことを成果として残せます。そこから先は、実際の業務結果を確かめながら、Skillだけでなくコード・権限・評価基準へと学びを還元していく段階です。