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

> CodexとClaude Codeの履歴からAgent Skillsの候補を見つけ、SKILL.mdと補助資産へ分け、Skillなし・旧版と比較して評価する作り方を解説します。共通仕様と両者で違う配置・起動・設定、安全設計、複数AIエージェントへの配布、差分履歴を使った運用まで整理します。

Canonical URL: https://labs.eastbraver.com/blog/agent-skills-design-evaluation
Published: 2026-08-23T20:21:00+09:00
Updated: 2026-09-09T00:00:00+09:00
Category: ai-development
Tags: ai-agent, agentic-infra, software-engineering

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

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

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

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

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

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

> [!NOTE] この記事の範囲
> Agent Skillsの共通仕様と、Codex・Claude CodeなどAIエージェントごとの違いを整理し、実務で使える作成手順へ落とし込みます。特定のAIエージェントが持つ全機能を列挙するリファレンスではありません。
> また、この記事で評価の中心に据えているのは、Skillの起動と成果の再現性です。AIを使った経験を組織全体の能力としてどう蓄積するかは、Skillだけで完結する話ではありません。

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

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

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

### 今回の履歴調査で確認した範囲

現在のリポジトリに対象を限定し、CodexとClaude Codeを別々に集計しました。

| Metric | Value | Context |
| --- | --- | --- |
| Codex履歴 | 482件 | 作業ディレクトリが一致するJSONL |
| Claude Code履歴 | 13件 | このリポジトリのプロジェクト履歴 |
| プロジェクト内のSkill | 17個 | .claude/skills配下のディレクトリ |
| 調査基準日 | 2026-08-23 | 再集計日 |

- Source: ローカルのCodex・Claude Code履歴とリポジトリ
- Method: リポジトリの作業ディレクトリとプロジェクト識別子で限定し、subagent履歴を除いて集計
履歴からSkillと評価ケースを作るまでには、選別と裏取りが必要です。私は次の流れで考えています。

### 履歴からSkillと回帰ケースを作る流れ

CodexとClaude Codeの履歴は、別々に抽出してから共通点と両者で異なる点を整理します。現在のコードとGitで裏を取り、Rule・Skill・script・評価ケース・一度限りの情報へ分類します。

![履歴からSkillと回帰ケースを作る流れ](/images/blog/agent-skills-design-evaluation/history-to-skill-flow.svg "1200x675")

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

*CodexとClaude Codeの履歴を別々に調べ 検証と分類を通して再利用できる形へ変える*

- Source: 公開後の再集計を含むローカル履歴調査
- Method: 履歴抽出・人の判断の選別・現在の実装による検証・配置先の分類
- Environment: このリポジトリのCodexとClaude Code履歴
図の最初で二つの履歴を混ぜていないのは、保存形式が違うからだけではありません。Codexでだけ繰り返す詰まりと、Claude Codeでだけ繰り返す詰まりを、共通点に丸めて消さないためです。

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

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

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

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

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

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

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

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

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

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

| 調べる履歴 | 対象の絞り方 | 残したい違い |
| --- | --- | --- |
| Codex | セッションに記録された作業ディレクトリがリポジトリと一致するもの | CodexのSkill探索、起動、承認、Tool利用で生じた詰まり |
| Claude Code | このリポジトリに対応するプロジェクト履歴 | Claude Codeのfrontmatter、slash command、hook、subagentで生じた詰まり |

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

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

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

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

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

> [!IMPORTANT] 採用と拒否を対で残す
> 最終回答だけでは、書き手が守りたかった境界を復元できません。採用した案、拒否した案、その理由を同じ評価ケースに残します。

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

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

| 履歴から見つかったもの | 置き場所 | 判断の目安 |
| --- | --- | --- |
| すべての作業で守る方針 | `AGENTS.md`や`CLAUDE.md`などのRules | 特定のSkillが起動しなくても常に必要 |
| 特定の仕事で使う判断と手順 | Skill | 入力・分岐・成果物・完了条件を繰り返し使う |
| 同じ入力から同じ結果を出す必要がある処理 | Skill内の`scripts/` | 抽出・変換・検証を固定した手順で実行する |
| 頻繁に変わる事実や参照情報 | ナレッジベースや`references/` | 手順と分離して更新し、必要な条件で読み込む |
| 必ず同じ結果にしたい判定や変換 | プログラムコード | 自然言語の解釈に委ねず、テスト可能な処理にする |
| 絶対に越えてはならない操作境界 | Tool権限・認可・隔離環境 | Skillの注意書きだけに頼らず、実行側で制限する |
| 二度と起こしたくない重大な失敗 | 自動テスト | Skillが起動しない状況でも回帰を止める |
| 失敗・訂正・採否の具体例 | 評価ケース | 改訂前後で同じ失敗が戻らないか判定できる |
| その案件だけの背景や私事 | 残さない | 別の仕事へ一般化できず、秘密情報を含み得る |

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

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

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

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

| 段階 | 読む範囲 | 残すcheckpoint |
| --- | --- | --- |
| 初回 | このリポジトリに属する全履歴 | 調査日と最後に確認したイベント |
| 通常運用 | checkpoint以降の差分 | 新しい訂正と評価ケースへの反映結果 |
| 大きな更新後 | 影響するSkillと周辺の過去履歴 | 再評価したAIエージェント・モデル・version |

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

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

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

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

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

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

| 仕組み | 主な役割 | Skillとの境界 |
| --- | --- | --- |
| System Prompt / Rules | 常に適用する方針と制約 | 常時必要な規則はSkillに隠さない |
| プロンプトの雛形 | 依頼文の再利用 | 入力を整えるだけならプロンプトで足りる |
| Tool / Function | 一つの能力や操作 | Toolの呼び出し順や判断をSkillに書く |
| MCP server | ライブデータや認証付き操作への接続 | 接続はMCP、仕事の進め方はSkillが担う |
| Hook | 対応イベントで呼び出す処理 | 呼び出しをモデルの任意判断から外し、失敗時の挙動も確認する |
| Subagent | 担当やコンテキストの分離 | 分担方法と担当者が従う手順を分ける |

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

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

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

| 仕事 | 失敗したときの影響 | Skillで固定する範囲 |
| --- | --- | --- |
| 読み取りだけの調査や下書き | 結果を捨ててやり直せる | 目的と評価軸を固定し、探索順には余地を残す |
| リポジトリ内のファイル変更 | 差分を戻せるが、見落としが残り得る | 対象範囲、編集規則、検証、完了条件を固定する |
| 公開・送信・削除・課金 | 外部の状態が変わり、回収できない場合がある | 対象解決、事前確認、実行順、停止条件を強く固定する |

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

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

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

```text
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エージェント側の仕組みです。

| 区分 | 含まれるもの |
| --- | --- |
| Agent Skillsのオープン仕様 | `SKILL.md`、`scripts/`、`references/`、`assets/` |
| OpenAI向けの任意拡張 | `agents/openai.yaml`、表示名、アイコン、ブランド色、起動方針、MCP依存 |
| 評価ガイドとAnthropicのSkill Creatorの規約 | Skill内の`evals/evals.json`、隣のワークスペース、`.skill`化での`evals/`除外 |

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

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

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

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

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

```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`に絞ります。

```markdown
---
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を見つけるための情報で、本文は起動後に実行する手順です。この二つは役割が違います。

| 部分 | 読まれる時点 | 担う判断 |
| --- | --- | --- |
| frontmatter | Skillを選ぶとき | `name`と`description`で仕事と起動条件を伝える |
| Markdown本文 | Skillが起動した後 | 入力・分岐・手順・出力・検証・停止条件を伝える |

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

| 使い方 | Skillが担うこと | 起動と読み込み |
| --- | --- | --- |
| 手順書 | 入力・分岐・実行順・検証・停止条件を揃える | 自動または明示起動後に`SKILL.md`を読む |
| 必要時に開く参考書 | 作業条件に合うドメイン知識へ案内する | `SKILL.md`の条件から必要な補助資料だけを読む |
| カスタムコマンド | 利用者がSkill名と引数を指定して仕事を始める | 対応するAIエージェントの明示起動方法を使う |

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

### nameは機械的に検証できる

[Agent Skills仕様の`name`要件](https://agentskills.io/specification#name-field)は明確です。

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

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

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

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

### descriptionには起動条件を書く

`description`には「何をするか」と「いつ使うか」の両方を書きます。[共通仕様の長さは1〜1,024文字](https://agentskills.io/specification#description-field)です。本文にだけ起動条件を書いても、本文を読むかどうかの判断には使えません。

[Agent Skillsのdescription設計ガイド](https://agentskills.io/skill-creation/optimizing-descriptions)も、狭すぎる説明は必要な場面で起動せず、広すぎる説明は不要な場面で起動すると説明しています。

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

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

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

```yaml
description: Helps with APIs.
```

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

```yaml
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作成ドキュメント](https://learn.chatgpt.com/docs/build-skills)でも、暗黙起動は依頼と`description`の一致で決まり、対象範囲と境界を簡潔に書くよう案内されています。
CodexではSkillが増えると、最初に見せる一覧の`description`が短縮され、一部のSkillが省略される場合もあります。個々の説明だけでなく、一覧に並んだときに区別できるよう設計する必要があります。

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

```text
exporting-csv
creating-csv
formatting-csv
validating-csv
```

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

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

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

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

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

```markdown
## 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](https://agentskills.io/specification#progressive-disclosure)は、この順序をメタデータ、指示、必要な資産の三段階として定めています。[OpenAIのスキル作成ドキュメント](https://learn.chatgpt.com/ja-JP/docs/build-skills)も、CodexはSkillを使うと判断した時点で`SKILL.md`の指示全文を読み込むと説明しています。

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

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

### Skillを段階的に読み込む流れ

Skillはnameとdescriptionで存在を知らせ、選ばれた場合にSKILL.md全文を開きます。補助資料はSKILL.mdの条件に応じて必要なものだけを追加で読み込みます。

- 利用可能なSkill一覧ではnameとdescriptionだけを確認します。
- 依頼と一致したSkillのSKILL.mdを読み込みます。
- SKILL.mdの条件に応じて、必要なreferencesなどの補助資料だけを追加で読み込みます。

*nameとdescriptionから必要なreferencesへ段階的に進む*

図の右端へ進むのは、起動後の手順が参照条件に該当した場合だけです。Skillを選ぶ前に`SKILL.md`と詳細資料をすべて読み込む構成は避けます。また、補助資料へリンクするだけで必ず読まれるとも限りません。[Claude Codeのcontext window解説](https://code.claude.com/docs/en/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仕様](https://agentskills.io/specification#optional-directories)は、`SKILL.md`を500行未満に保ち、詳細な資料を別ファイルに分けることを推奨しています。
500行は合否を決める魔法の数字ではありません。ただ、Skillが起動すると本文全体が読み込まれるため、本文を短く保つ設計上の理由はあります。

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

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

| 要素 | 入れるもの | 入れないもの |
| --- | --- | --- |
| `SKILL.md` | 判断・手順・参照条件・出力条件 | 長大な仕様と大量の例 |
| `scripts/` | 検証・変換・抽出・定型生成 | 再利用や結果の固定、検証のために保存する必要がない一度限りの処理 |
| `references/` | 規約・スキーマ・詳細手順・例 | 実行順を決める中核ルール |
| `assets/` | テンプレート・画像・雛形 | 行動規則や判断ロジック |

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

### Skillパッケージの責務境界

Skillは必要な依頼で起動し、SKILL.mdが判断と手順を統括します。常時規則、同じ入力から同じ結果を出す処理、外部接続、イベント処理は、それぞれ適した境界へ分離します。

![Skillパッケージの責務境界](/images/blog/agent-skills-design-evaluation/skill-responsibility-boundaries.svg "1200x675")

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

*Skillは判断と手順を中心に置き 常時規則と実行境界を外へ分ける*

- Source: 本記事の責務分担
- Method: 本文で説明した配置原則を構造化
図の中央に置いた`SKILL.md`には仕事の進め方をまとめ、条件に応じて専門知識・同じ入力から同じ結果を出す処理・成果物素材・外部能力を呼び分けます。

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

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

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

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

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

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

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

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

```markdown
- 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](https://agentskills.io/specification#file-references)は、参照を`SKILL.md`から一段の深さに保ち、深く入れ子になった参照チェーンを避けるよう推奨しています。これは二階層以上を禁止する要件ではありません。補助資料も必要時に読み込まれるため、リンクの存在だけで読まれることを保証するものではありません。

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

| 区分 | この記事で扱う内容 |
| --- | --- |
| 公式仕様で確認できる事実 | 起動前は`name`と`description`、起動時は`SKILL.md`全文、補助資料は必要時に読み込む。一段参照を推奨する |
| 公式資料を踏まえた設計判断 | `SKILL.md`へ「何が書かれていて、どの条件で読むか」を一行ずつ書く |
| ローカル観測 | 条件を再現できない過去の環境で、深い参照先が読まれないことがあった |

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

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

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

> [!IMPORTANT] 判断規則と素材を分ける
> テンプレートをどう選び、いつ使うかは`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`](https://learn.chatgpt.com/docs/build-skills)は、Skillの目的、起動条件、スクリプトの要否を聞き取り、`SKILL.md`と補助ファイルの初稿を作ります。現行の`SKILL.md`と同梱スクリプトには、評価ケースを実行して比較する手順は含まれていません。[Anthropicが公開するSkill Creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)は、初稿に加えて、評価ケースの作成、Skillなしや旧版との比較、採点、集計、`description`の調整まで自動化します。

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

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

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

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

次は管理例です。Agent Skills仕様は評価の形式を定めていません。[Agent Skillsの評価ガイド](https://agentskills.io/skill-creation/evaluating-skills)は成果の評価を`evals/evals.json`、[description最適化ガイド](https://agentskills.io/skill-creation/optimizing-descriptions)は起動の評価を`should_trigger`付きの問い合わせ一覧として別々に扱いますが、ここでは三件を一覧できるよう一つにまとめています。

```json
[
  {
    "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評価の技術ガイド](/guides/ai-agent-evaluation)で整理しています。この記事で扱うのは、Agent Skillsに固有の起動条件と、Skillを変更した効果の測り方です。

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

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

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

### Skillを育てる評価ループ

Skillの改訂は、同じ条件でSkillなし、旧版、候補版を比較して判断します。実際の失敗と人の訂正を回帰ケースへ戻すことで、一度の成功ではなく再現性を高めます。

![Skillを育てる評価ループ](/images/blog/agent-skills-design-evaluation/skill-evaluation-loop.svg "1200x675")

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

*同じ条件の比較と回帰ケースへの還流で改訂効果を確かめる*

- Source: 本記事の評価手順
- Method: 比較条件と回帰ループを構造化
図の上段にある比較条件が揃って初めて、候補版による差を読めます。右下の分岐は、外部送信や削除などの重大な安全違反を、ほかの評価項目の平均点で埋めないことを示しています。

| 評価面 | 確認すること | APIレビューSkillの例 |
| --- | --- | --- |
| 起動 | 必要な依頼で起動し、対象外や隣接Skillの仕事を奪わないか | API差分のレビューでは起動し、告知文の作成では起動しない |
| 判断 | 正しいTool・command・対象範囲・権限を選び、不足情報を取得できるか判断するか | 許可されたリポジトリやPRから差分を取得し、解決できない不足だけを質問する |
| 成果 | 必須成果物と検証が終わり、内容が正しいか | 互換性の指摘・根拠・必要な対応が揃っている |
| 実動作 | 選ばれた操作を実行したToolやCLIが、禁止対象に触れず、読み取り範囲と副作用が契約どおりか | 対象外のファイルを読まず、確認前に外部へ送信しない |
| 品質 | 優先順位・分かりやすさ・実用性が目的に合うか | 重大な指摘と推奨事項を読み分けられる |
| 安定性と効率 | 複数回の成功率と失敗傾向、時間・トークン・Tool呼び出しが妥当か | 重要なケースを繰り返しても重大な見落としが戻らない |

起動が正しくても、成果が期待と違えば失敗です。最終回答が自然でも、必要なファイルが作られていない、誤った対象を更新した、確認前に外部へ送信したのであれば合格にはできません。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が互換性の問題を正確に指摘しても、改修前に担当チームへ届かず障害を防げなければ、業務として成功したとは言えません。

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

| 評価する層 | 問うこと | 残す根拠 |
| --- | --- | --- |
| Skillの評価 | 必要な場面で起動し、安全に期待する成果を再現できたか | 起動結果、成果物、Tool記録、回帰ケース |
| 業務の評価 | 顧客や現場にとって望ましい結果につながったか | 手戻り、事故、完了結果、現場の確認 |
| 組織の評価 | 判断理由と改善内容を別の担当者や環境へ引き継げるか | 評価基準、変更理由、テスト、運用記録 |

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

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

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

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

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

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

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

| 評価する軸 | 確認すること |
| --- | --- |
| 対象Skillの隔離 | 一覧だけでなく、別の探索先・コピー・直接ファイル参照から対象Skillを利用していないか |
| 比較条件の統一 | Rules・他のSkill・Tool・権限・モデル設定・初期ファイル状態が三条件で同じか |

新しい会話でも、前の試行のファイルやキャッシュが残ることはあります。[評価ガイド](https://agentskills.io/skill-creation/evaluating-skills)に沿って、コンテキストと実行環境を別々に初期化します。対象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の評価解説](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)でも、過去試行のGit履歴から答えを得るような評価汚染を防ぐため、試行環境の隔離を扱っています。

| 資産 | 置き場所 | 残す内容 |
| --- | --- | --- |
| ケース | Skill内の`evals/` | 入力、起動の期待、合格条件、禁止条件、調整用・回帰用・採用判断用の別 |
| 採点の契約 | Skill内の`evals/` | grader、runner、結果のschema、graderが拒否すべき反例 |
| 比較対象 | Skill内の`evals/` | 旧版のbaseline、Skillなし・旧版・候補版を識別できるcommitまたはversion |
| 実行条件 | Skill内のbenchmark | AIエージェント、モデル、Tool、権限、OS、依存version、対象Skillの隔離と比較条件の統一 |
| 実行結果 | ワークスペース | 成果物、Tool記録、機械判定、人または評価用モデルの根拠 |
| 集計 | Skill内のbenchmark | 合格率、失敗の種類、p50・p95・最大時間、トークン、Tool呼び出し回数、証明できたことと未証明の限界 |

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

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

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

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

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

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

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

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

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

[OpenAIの評価ガイド](https://developers.openai.com/api/docs/guides/evaluation-best-practices)は、実際のログからタスク固有の評価例を集め、変更のたびに継続評価する方法を勧めています。Skillでは、会話履歴に残った失敗と人間の訂正を次の流れで使えます。

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

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

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

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

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

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

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

| ケース | 期待する起動 | 確認する境界 |
| --- | --- | --- |
| Skill名を明示した対象作業 | 起動する | 明示起動で正しいSkillを選べる |
| Skill名を使わない自然な対象作業 | 起動する | 利用者の言い回しを`description`が拾える |
| 同じファイル形式を扱う別目的の作業 | 起動しない | 形式と仕事の目的を区別できる |
| 近い名前の別Skillが担う作業 | 起動しない | 隣接Skillの責務を奪わない |

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

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

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

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

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

| 判定方法 | 向いている対象 | 残すもの |
| --- | --- | --- |
| スクリプトによる機械判定 | ファイルの有無、JSON Schema、テスト結果、Tool引数、禁止操作 | 終了コード、検証結果、操作記録 |
| 人または評価用モデルの判断 | 文章の分かりやすさ、優先順位、書き手らしさ、デザインの使いやすさ | 判断基準、判定、根拠 |

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とgraderを直すとき | 失敗を観察し、修正の材料にする |
| 回帰用 | 過去の失敗を固定するとき | 修正後も同じ失敗が戻らないことを確認する |
| 採用判断用 | 採用を判断するとき | 調整には使わず、事前に決めた試行回数で最後に評価する |

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

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

| 記録 | 判断できること |
| --- | --- |
| 複数試行の合格率 | 新しい会話でも成功を繰り返せるか |
| 失敗の種類 | 確認漏れや見落としなど重大な失敗が残っていないか |
| 所要時間・トークン数・Tool呼び出し回数 | 成果に対して実行コストが妥当か |
| 読み取りbyte数・外部状態の変更数・確認回数 | 契約どおりの範囲と手順で動いたか |
| 停止や確認を引き起こしたSkillのファイル・該当指示・解釈 | 必要な確認か、曖昧な指示から生まれた不要な停止か |
| graderと人の判定の不一致 | graderをまだ信頼してよいか |
| 最も時間がかかった結果 | 平均値に隠れた遅い実行がないか |

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

Skillの評価そのものを公開ベンチマークで証明している事例ではありませんが、Bunのリポジトリには測定と回帰防止の設計として参考になる実装があります。ここでは調査対象をcommit [`06820dc`](https://github.com/oven-sh/bun/tree/06820dc10fd31bc21c7a7e65743978a62d00843d)へ固定しました。

| Bunで確認できたこと | Skill評価へ移せる考え方 |
| --- | --- |
| [直近CIのプラットフォーム別中央値から所要時間表を作る](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/scripts/update-test-durations.mjs) | 実測時間を基準に評価ジョブを分ける |
| [時間表は5ビルド、並列許可リストは300ビルドから更新する](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/.buildkite/update-test-durations.yml) | 速度指標と安定性の昇格で、必要な履歴量を分ける |
| [50ビルド未満では並列許可リストを生成しない](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/scripts/update-parallel-allowlist.mjs) | 観測が足りないケースは安全な直列実行に残す |
| [各プラットフォームの最大時間を採用する](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/scripts/ci-slowest-tests.ts) | 平均だけでなく、p95・最大値・最も遅い環境を見る |
| [`verify` Skillが変更を反映したdebug binaryの直接実行を求める](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/.claude/skills/verify/SKILL.md) | 実際に読み込まれたSkillの版と実行結果を確認する |
| [`REVIEW.md`が修正の重要部分を外すとテストが失敗することを求める](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/REVIEW.md) | アブレーションや反例で、評価が変更の効果を検出できるか確認する |
| [Claude Code hookが既知の誤操作を実行前に止める](https://github.com/oven-sh/bun/blob/06820dc10fd31bc21c7a7e65743978a62d00843d/.claude/settings.json) | 説明だけで防げない反復失敗をHookやvalidatorへ移す |

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

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

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

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

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

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

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

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

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

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

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

[AnthropicのAgent Skillsドキュメント](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#security-considerations)も、信頼できる出所だけを使い、`SKILL.md`・`scripts/`・画像を含む同梱ファイルを監査するよう求めています。外部URLから追加情報を取得するSkillは、取得先の内容が後から変わる点にも注意が必要です。

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

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

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

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

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

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

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

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

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

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

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

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

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

| 観点 | Codex | Claude Code |
| --- | --- | --- |
| プロジェクト内の探索場所 | `.agents/skills/` | `.claude/skills/` |
| 明示的な起動 | `$skill-name`またはSkill一覧から選択 | `/skill-name` |
| 自動起動の入口 | `description` | `description`と`when_to_use` |
| 追加設定 | `agents/openai.yaml` | `SKILL.md`のClaude Code向けfrontmatter |
| 分離して実行する仕組み | 通常のSkill本文とは別に担当分離を設計 | `context: fork`と`agent`を指定できる |
| 評価ケースの規約 | ドキュメントに定めなし | Skill Creatorが`evals/evals.json`と隣のワークスペースを使う |

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

[OpenAIのSkill作成ドキュメント](https://learn.chatgpt.com/docs/build-skills)によると、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へ持っていくときも共通核が崩れません。

> [!NOTE] Codex向けファイルの境界
> 共通の実行手順は`SKILL.md`に残します。CodexやChatGPTの画面表示、起動方針、MCP依存だけを`agents/openai.yaml`へ足します。

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

[Claude CodeのSkillドキュメント](https://code.claude.com/docs/en/skills)は、プロジェクトの`.claude/skills/`、個人の`~/.claude/skills/`、Pluginに含まれるSkillを扱います。

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

| 設定 | 何を変えるか |
| --- | --- |
| `when_to_use` | 自動起動を検討する場面を補足する |
| `disable-model-invocation` | 自動起動を止め、利用者からの明示起動だけにする |
| `user-invocable` | slash commandとして利用者に見せるかを決める |
| `allowed-tools` | 起動したターンで列挙したToolを追加確認なしで使えるようにする。未列挙のToolを禁止する設定ではない |
| `disallowed-tools` | 起動したターンで指定したToolを利用可能なTool群から除外する |
| `context: fork`・`agent`・`background` | 別コンテキストで実行し、担当やバックグラウンド実行を指定する |
| `hooks`・`paths`・`shell` | Skillに紐づくhook、対象パス、実行環境を指定する |
| `model`・`effort` | Skillで使うモデルと推論量を指定する |
| `argument-hint`・`arguments` | slash commandで受け取る引数と表示を定義する |

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

2026年9月9日に確認した[Claude Codeの仕様](https://code.claude.com/docs/en/skills#pre-approve-tools-for-a-skill)では、どちらの付与・制限も次のユーザーメッセージで解除されます。`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/`からシンボリックリンクで参照しています。

```text
.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管理ドキュメント](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/using-agent-skills.md)も、プロジェクトの`.agents/skills/`を`.gemini/skills/`の別名として案内しています。

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

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

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

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

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

公式の規約は、この境界を二段で引いています。手書きの評価ケースはSkill内の`evals/`に置き、実行のたびに増える結果と集計は隣のワークスペースへ分けます。`evals/`はSkillと一緒に版管理されるため、Gitやplugin marketplace経由の配布では同梱されます。実際に[Anthropicの公式pluginリポジトリ](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/math-olympiad/skills/math-olympiad)には、`evals/`を含んだまま配布されているSkillがあります。一方、[Skill Creatorのパッケージ処理](https://github.com/anthropics/skills/blob/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/skill-creator/scripts/package_skill.py)が作る`.skill`アーカイブでは、Skillルート直下の`evals/`が除外されます。

```text
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を変えたときに何をどの条件で証明したかを追えるからです。

| 資産 | 置き場所 |
| --- | --- |
| 評価ケース、grader、runner、結果のschema | Skill内の`evals/` |
| 旧版のbaseline、採用判断に使った小さなbenchmark | Skill内の`evals/` |
| graderが拒否すべき反例のfixture | Skill内の`evals/` |
| 一時的なtrace、大容量の実行結果、再生成できる中間物 | ワークスペースまたはGitの無視対象 |
| 秘密情報を含み得る入出力、API responseの全文 | 版管理しない |

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

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

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

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

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

| 見直すきっかけ | 確認すること |
| --- | --- |
| 同じ訂正や手動介入が再発した | Skillの規則不足か、Rule・script・Hookに置くべき内容か |
| Codex・Claude Code・モデル・Toolが更新された | 探索、起動、権限、frontmatter、出力の前提が変わっていないか |
| 隣接するSkillを追加または変更した | `description`が競合し、誤起動や取りこぼしが増えていないか |
| 評価の合格率・時間・コストが悪化した | 失敗の種類、p95、最大値、特定の環境への偏り |
| 長期間使われていない | 常時Ruleや別Skillと重複していないか、廃止できるか |

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

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

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

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

| 評価に加える場面 | 確認する挙動 |
| --- | --- |
| 依頼文にない入力を許可された取得元から解決できる | 情報を捏造せず、取得して作業を進める |
| 変更に対応する必須検証がすべて通っている | 新たな根拠なしに検証を広げず、成果物を仕上げる |
| Skillの指示を理由に停止や追加確認が発生する | 該当ファイルと指示を記録し、明示された要求とモデルの解釈を区別する |
| 独立した作業を並列化する価値があり、委譲が許可されている | 委譲の有無と、分割・統合を含む所要時間を比較する |

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

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

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

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

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

| 一緒に持ち運ぶもの | 残す理由 |
| --- | --- |
| Skillと判断理由 | 手順の意図を理解し、前提が変わったときに修正するため |
| 合否を決める評価ケース | 移植先でも同じ品質と安全性を再評価するため |
| Toolやデータの接続条件 | 入出力と依存関係を別の環境で再現するため |
| 認可ポリシーと安全境界 | モデルの指示追従だけに禁止操作を預けないため |
| 変更履歴と不採用理由 | 過去に退けた失敗へ戻らず、次の改訂材料にするため |

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

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

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

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

| 失敗 | 起こること | 直し方 |
| --- | --- | --- |
| 巨大な万能Skill | `description`が広がり、不要な場面でも起動しやすくなる | 入力・完了条件・評価軸が共通でない仕事を別のSkillへ分ける |
| `SKILL.md`に全資料を詰め込む | 起動のたびに背景知識やAPI仕様まですべて読み込む | 判断に必要な核だけを残し、詳細を読む条件とともに`references/`へ移す |
| 強い命令を増やして失敗を抑える | 入力不足・曖昧な分岐・検証処理の欠如が残る | 失敗箇所を観察し、入力契約・判断分岐・機械検証のどこで止めるかを決める |
| 出力例を唯一の正解にする | 入力が変わっても例の固有値や文章を模倣する | 守るスキーマと必須項目を規則にし、例を一つの具体例として分ける |
| 作成者の会話内だけで評価する | 会話に残った目的や修正履歴に助けられた結果を採用する | 新しい会話でSkillだけから必要な情報が伝わるかを確認する |

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

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

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

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

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

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

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

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

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

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

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

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

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

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