CodexのSubagentだけTOMLなのはなぜか — AGENTS.md・Skills・Subagentの役割分担

AGENTS.mdとSkillsは.mdなのに、Subagentだけ.tomlという違和感

Codexで仕組み化を始めると、扱うファイルは大きく3種類になります。プロジェクトのルールを書く AGENTS.md、繰り返し業務の手順を書く SKILL.md、そして役割を持った担当を定義するサブエージェントです。ここで拡張子を並べてみると、前の2つはマークダウン（.md）なのに、サブエージェントだけが .codex/agents/reviewer.toml のようにTOML形式になっています。

同じ「Codexに何かを教えるファイル」なのに、なぜ書式が揃っていないのか。当社でも最初にこの構成を見たときは、歴史的な事情の名残りだろうかと考えました。しかし公式ドキュメントを読み込んでいくと、これは統一し忘れではなく、3つが担っている役割そのものが違うことの表れだとわかります。

答え — 「読ませる指示書」と「AIそのものの設定」

結論を先に書きます。AGENTS.mdとSKILL.mdはAIに読ませる自然言語の指示書で、サブエージェントの .toml はAIそのものを組み立てる設定ファイルです。前者は「文章」なので文章に適したマークダウン、後者は「設定値の集まり」なので設定に適したTOML——役割が違うから、器も違うというだけの話です。

一言でまとめるなら、マークダウンは「AIに読ませる文章」、TOMLは「Codexが読み取る設定値」です。読み手が違うのだから、書式が分かれているほうがむしろ自然だった、ということになります。

AGENTS.mdは「何を守るか」

AGENTS.mdは、Codexが仕事を始める前に読み込むプロジェクト固有のルールと前提情報です。公式ドキュメントでも「自然言語の指示と文脈を書いたプレーンなマークダウンファイル」と定義されており、特別な記法は要りません。作業を始めるときに、グローバル（~/.codex/AGENTS.md）から作業フォルダの階層まで順に読み込まれ、手元に近いものほど強く効きます。

# AGENTS.md

## 基本方針
- 回答・成果物は日本語で書く
- ファイルを変更する前に、既存の書き方を確認する
- 作業が終わったら、何をどう変えたかを箇条書きで報告する

## 禁止事項
- 顧客名を社外向けの文面に出さない

中身の中心は最後まで自然言語です。だからマークダウンが適しています。書き方の詳細はAGENTS.mdの書き方で解説しています。

SKILL.mdは「仕事のやり方」

Skillsも中心は自然言語です。公式では、スキルを手順書・参照資料・必要に応じたスクリプトをひとまとめにしたものと説明しており、その中心に SKILL.md を置きます。実体は1枚のファイルではなく、SKILL.md を中心としたディレクトリです。

my-skill/
├── SKILL.md      ← 手順本体（自然言語）
├── scripts/      ← 手順の中で実行させたい処理
├── references/   ← 参照させたい資料
└── assets/       ← ひな形・素材

SKILL.md の冒頭には、スキル名と「どんなときに使うか」の説明だけを短く書き、その下は「①元資料を確認する ②要点を抽出する ③この形式でレポートにする」といった手順と判断基準が続きます。つまり、機械が読む部分はごくわずかで、大半は人が読んでも意味のわかる文章です。置き場所が .codex ではなく .agents/skills である理由はCodexのSkillsが.agents配下にある理由で解説しています。

Subagentは「どんなAIを立ち上げるか」

ここが決定的に違います。サブエージェントの定義ファイルに書くのは、指示だけではありません。公式ドキュメントによると、必須項目は name・description・developer_instructions の3つで、これに加えて、通常の設定ファイル config.toml の項目もそのまま書けるとされています。

# .codex/agents/pre-check.toml
name = "pre-check"
description = "社外へ出す文書の最終チェック担当。表記ゆれと出してはいけない情報を洗い出す"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
あなたは社外提出前のチェック担当です。
渡された文書を1文ずつ確認し、次の3点を一覧で報告してください。
1. 社名・製品名・敬称の表記ゆれ
2. 社外に出すべきでない情報（顧客名・未公開の数値）
3. 事実確認が取れていない断定表現
文書そのものは編集しません（指摘のみ）。
"""

見てのとおり、ここで決めているのは「何をするか」だけではありません。どのモデルを使い、どの推論強度で、どこまでの権限を与え、どの外部ツールとスキルを持たせるか——採用でいえば職務内容だけでなく、席・権限・支給する道具まで含めて決めている状態です。これは文章というより、構造化された設定データです。そして実際、この定義ファイルは通常の設定ファイル config.toml と同じ項目を受け付ける「部分集合」として設計されています。同じ設定を書くファイルなのだから、形式も設定ファイル本体と同じTOMLで揃っている——これが一番自然な説明です。

TOMLの中に自然言語がある、という入れ子構造

面白いのは、サブエージェントの .toml にも developer_instructions という項目があり、その中身は自然言語の指示書だという点です。つまり設定ファイルが自然言語の指示を1つ抱えている、という構造になっています。

subagent.toml
│
├─ name                    ← 設定
├─ model                   ← 設定
├─ model_reasoning_effort  ← 設定
├─ sandbox_mode            ← 設定
├─ mcp_servers             ← 設定
├─ skills.config           ← 設定
│
└─ developer_instructions
      ↓
   自然言語の指示

AGENTS.mdやSKILL.mdが「ほぼ全部が自然言語で、機械が読む部分がおまけ」だとすれば、サブエージェントの .toml はほぼ全部が設定で、自然言語がその中の1項目という逆の比率になっています。同じ「AIに渡すファイル」でも比率が反転しているので、器が分かれた——そう捉えると腹落ちします。

Claude Codeとの違い — 器にするのは文章か、設定か

「ではなぜClaude Codeはサブエージェントも .md なのか」という疑問が残ります。実はClaude Codeも、名前・説明・使うモデル・使えるツールといった設定を持たせています。違うのは置き方で、Claude Codeはマークダウンファイルの先頭に設定をまとめて書き、その下に自然言語の指示を続ける形をとっています（詳細はClaude Codeのサブエージェントで解説しています）。

つまり両者の差は「設定を持つか持たないか」ではなく、設定と自然言語のどちらを器にするかです。Claude Codeは文章のファイルに設定を同居させ、Codexは設定のファイルに文章を同居させました。前者は1つの形式だけ覚えれば済む分かりやすさがあり、後者は設定項目が増えても config.toml の作法がそのまま使えるという一貫性があります。どちらが正しいという話ではなく、整理の哲学の違いです。両ツールの考え方の違いはCodexとClaude Codeの比較でも整理しています。

実務への示唆 — 形式が違うものは、更新する人もレビューも違う

ここまでの話は拡張子の豆知識にとどまりません。形式の違いは、そのファイルを誰が書き、誰が確認し、どれくらいの頻度で更新するかの違いとして現れます。当社が支援先で仕組み化を設計するときも、この3階層は別の運用ルールを当てています。

特に注意したいのが3行目です。.toml には sandbox_mode のようにその担当がファイルを書き換えられるかどうかを決める項目が含まれます。チェックやレビューを任せる担当は read-only にしておけば「指摘はするが勝手に直さない」担当になり、レビューの独立性も保てます。この考え方は権限設計そのものなので、AGENTS.mdを1行足すのと同じ気軽さで扱わないほうが安全です（権限の全体像はCodexのセキュリティ設定で解説しています）。

• 毎回守ってほしいことはAGENTS.mdへ — 特定の担当だけでなく、その現場の全員に効かせたいルールです
• 繰り返す業務の手順はSkillsへ — 手順と判断基準を自然言語で書けば、他のツールへ持ち運びやすい資産になります
• 役割・権限・道具の組み合わせはサブエージェントへ — 「誰に何をさせるか」が固まってから定義すると、無駄な担当が増えません

逆に言えば、この3つの区別が曖昧なまま仕組み化を進めると、AGENTS.mdに特定業務の手順が流れ込んで肥大化したり、サブエージェントを増やしたのに成果が変わらないという状態になりがちです。実際に分担させるところまで含めた進め方はCodexのサブエージェントと並列実行にまとめています。

当社自身、40以上の業務をAIエージェントに任せる中で、この「ルール・手順・担当」の3階層を1つずつ整備してきました。どこから手を付けるか、どの業務を手順化し、どの役割を担当として切り出すか——当社のCodex研修・導入伴走支援では、貴社の実業務を題材に、3階層の設計から運用の定着までを一体でご支援しています。