CodexへSkillsを追加すると、特定の仕事の進め方を細かく教えられる。
たとえばフロントエンド開発なら、画面作成、要件の読み取り、ブラウザテスト、build、デザインシステムといった仕事ごとにSkillsを用意し、関連するものを組み合わせて使える。VueやFigmaはその一例で、注目したいのは1つの大きな仕事を、複数のSkillsの組み合わせへ分けられることだ。
ただ、Skillsを増やすたびに同じAgentへ追加していくと、そのAgentは画面実装、ドキュメント読解、ブラウザ操作、テスト、インフラ、レビューなど、性質の違う仕事のSkillsをまとめて抱えることになる。
数個なら気にならなくても、用途が広がれば10個、20個、30個と増えていく。そこで考えたいのが、どのSkillsを組み合わせるかと、その組み合わせをどのAgentへ持たせるかという2つの設計だ。
Skillsは仕事のまとまりで組み合わせる
フロントエンド開発を例にすると、Skillsは次のような単位で組み合わせられる。
| 工程 | Skillsの組み合わせ | 仕事 |
|---|---|---|
| ページ作成 | Figma系 + フレームワーク系 | 画面の構造と見た目を作る |
| ロジック実装 | ドキュメント系 + フレームワーク系 | APIやフォームなどを実装する |
| テスト | ブラウザ系 + Playwright | 実際の操作を確認する |
| build | フレームワーク系 + Playwright | 型チェックや回帰確認をして成果物を作る |
| デザインシステム | Figma library系 + Code Connect + フレームワーク系 | デザインと実装を長期的にそろえる |
この例は5組で、表に出てくるSkillを延べで数えると12個になる。デザインシステム工程で使うfigma-useまで含めれば延べ13個だ。同じSkillを複数工程で使うため、重複を除けば9種類になる。
9種類だけを見れば、それほど多く感じないかもしれない。しかし、同じ方法で開発全体をカバーしようとすると候補はすぐに増える。
Frontend
├─ Design
├─ Framework
├─ Browser test
└─ Build
Backend
├─ API design
├─ Database
└─ Integration test
Repository
├─ GitHub
├─ PR review
└─ Release
Infrastructure
├─ Docker
├─ Cloudflare
└─ Monitoring
Documentation
├─ Markdown
├─ PDF
└─ Diagramこれらをすべて1つのAgentへ追加すれば、やがて「何でもできるAgent」になる。機能するかどうかより、毎回の仕事で必要のないSkillまで候補として持ち続ける構成になることの方が気になる。
Skill本文は必要なときに読む。それでも一覧はコンテキストに入る
Codexは、設定されているすべてのSKILL.mdを最初から全文読み込むわけではない。必要なSkillを選び、その本文や関連資料を必要に応じて読む。
一方、OpenAIが公開しているCodex agent loopの解説では、Skillsが設定されている場合、初期プロンプトへ各Skillのメタデータを加えるとしている。Skillの名前や説明など、選択に必要な情報は仕事を始める時点から存在する。
https://openai.com/ja-JP/index/unrolling-the-codex-agent-loop/
概念的には次のような状態になる。
Skill A
name + description + metadata
Skill B
name + description + metadata
Skill C
name + description + metadata
...10個が20個になれば、その分だけメタデータも増える。30個、50個でも同じだ。SKILL.md本文を遅延して読む仕組みは、すべての詳細を常駐させないために有効だが、Skillを増やすこと自体のコストがなくなるわけではない。
さらにCodexは、ファイルを読み、コマンドを実行し、その結果を受け取って次の判断へ進む。AgentのコンテキストにはSkills以外の情報も積み上がっていく。
初期プロンプト
├─ Agentへの指示
├─ AGENTS.md
├─ Skillメタデータ
├─ Tool定義
└─ ユーザーの依頼
↓
ファイル・コマンド・テスト結果が追加されるCodexにはcompactionやprompt cachingもあるため、Skillが少し増えただけで急に使えなくなるわけではない。それでも、仕事に関係しないSkillsまで最初から候補へ入れておく必要はない。
OpenAIのモデルガイダンスでも、Coding AgentではプロンプトやToolの構成を必要な範囲に絞る方向が示されている。
Model guidance | OpenAI API
Compare model features, migration guidance, and prompting best practices across OpenAI models.
https://developers.openai.com/api/docs/guides/latest-model
Skillを分けたなら、Agentの境界にも使える
Skillsを細かく分けても、最終的にすべてを1つのAgentへ集めると、Agentから見える候補は増え続ける。
General Agent
├─ design-to-code
├─ framework-best-practices
├─ documents
├─ browser-test
├─ playwright
├─ api-review
├─ database
├─ security-review
├─ release-check
├─ deployment
└─ ...そこで、関連するSkillsの組み合わせを、そのままAgentの役割へ対応させる。
Coordinator Agent
│
├─ UI Agent
│ ├─ Design Skill
│ └─ Framework Skill
│
├─ Logic Agent
│ ├─ Requirements Skill
│ └─ Framework Skill
│
├─ Test Agent
│ ├─ Browser Skill
│ └─ Test Skill
│
└─ Build Agent
├─ Framework Skill
└─ Build / Test SkillUI Agentは画面を作るためのSkillsを持ち、Test Agentはブラウザ操作とテストに必要なSkillsを持つ。Test AgentがFigmaからデザインを読む手順まで知っている必要はないし、Build Agentがデザインシステム構築のSkillを持つ必要もない。
この形なら、Agentの役割とSkillの組み合わせを同じ境界で切れる。
親Agentは作業手順よりワークフローを持つ
複数Agentを使うなら、親Agentまで専門Skillsを大量に持たせる必要はない。
親Agentが知りたいのは、各分野の細かな作業手順ではなく、どの仕事を誰へ渡し、何を受け取れば次へ進めるかという流れだ。
Coordinator
|
| 「画面の骨格を作る」
v
UI Agent
|
| 実装結果
v
Coordinator
|
| 「業務ロジックを追加する」
v
Logic Agent
|
| 実装結果
v
Coordinator
|
| 「動作を確認する」
v
Test Agent親Agentには、たとえば次の情報があればよい。
- どの仕事をどのAgentへ渡すか
- 入力として何を渡すか
- 何を成果物として返してもらうか
- どの条件を満たしたら次へ進むか
Figmaの読み方やPlaywrightの細かな操作方法は、それを担当するAgent側へ置ける。Agentを分ける意味は担当者を増やすことではなく、その仕事に必要なコンテキストだけを持たせやすくすることにある。
Sub-agentを作るだけではSkillsは分離されない
CodexではCustom Agentを.codex/agents/*.tomlなどで定義でき、name、description、developer_instructionsに加えて、model、sandbox、MCP、skills.configなどもAgentごとに設定できる。
Subagents | ChatGPT Learn
Use subagents in ChatGPT and Codex, and configure custom Codex agents
https://developers.openai.com/codex/subagents
ここで注意したいのがskills.configの継承だ。公式ドキュメントでは、Custom Agent側でskills.configを省略すると親Agentの設定を継承すると説明されている。
そのため、親Agentに30個のSkillsが設定されている状態でSub-agentだけ追加しても、Skillの範囲を分けたことにはならない。
Parent Agent
Skills: 30個
↓ spawn
Test Agent
skills.config: 指定なしAgentを分けるなら、そのAgentが見るSkillsも合わせて絞る必要がある。Codexでは、不要なSkillをAgent単位で無効化できる。
[[skills.config]]
path = "/path/to/unrelated-skill/SKILL.md"
enabled = false公式のCustom Agent例でも、特定のAgentで不要なSkillを無効化する設定が使われている。
Subagents | ChatGPT Learn
Use subagents in ChatGPT and Codex, and configure custom Codex agents
https://developers.openai.com/codex/subagents
SkillsだけでなくToolと権限も分けられる
Agentの役割が決まると、必要なToolや権限も見えやすくなる。
| Agent | Skills | Tool・権限 |
|---|---|---|
| UI Agent | Design + Framework | Figma、ファイル編集 |
| Logic Agent | Requirements + Framework | ファイル編集、必要なAPI資料 |
| Test Agent | Browser + Test | Browser、Playwright |
| Review Agent | Review + Security | read-only |
| Build Agent | Build + Test | shell、buildコマンド |
コードレビューだけを行うAgentならread-onlyでもよいし、テスト担当Agentに本番デプロイの権限まで渡す必要はない。
OpenAIのCustom Agentの例でも、コード調査、レビュー、ドキュメント確認、ブラウザデバッグ、実装修正といった役割ごとにAgentを分け、sandboxやMCPを変えている。
Subagents | ChatGPT Learn
Use subagents in ChatGPT and Codex, and configure custom Codex agents
https://developers.openai.com/codex/subagents
Skillsの境界から考え始めても、最終的には「このAgentには何を見せ、何を操作させるのか」という設計につながる。
AgentはSkill単位ではなく仕事単位で分ける
ここまでをそのまま当てはめて、1 Skillにつき1 Agentとする必要はない。
Skill A -> Agent A
Skill B -> Agent B
Skill C -> Agent CAgentを分ける単位は、Skillそのものより1つの成果物や完了条件を共有する仕事のまとまりで考えた方が自然だ。
画面を作る仕事なら、デザインを読むSkillとフレームワークの書き方を守るSkillを同じAgentが使ってよい。どちらも同じ成果物を作るために必要だからだ。
一方で、画面実装、セキュリティレビュー、本番デプロイでは、必要な情報もToolも権限も完了条件も違う。こうした境界はAgentを分ける理由になる。
判断するときは、Skill数だけでなく次の違いを見ると分かりやすい。
| 観点 | 同じAgentにしやすい | 分けやすい |
|---|---|---|
| 成果物 | 同じファイルや同じ変更を作る | 別の成果物を作る |
| Skills | 強く関連している | ほとんど重ならない |
| Tool | 同じToolを使う | Browser、DB、deployなど大きく異なる |
| 権限 | 同じ権限でよい | read-onlyとwrite、本番権限などが異なる |
| 完了条件 | 一続きに確認できる | 独立した検証が必要 |
| コンテキスト | 同じ情報を読む | 必要な資料やコード範囲が違う |
この考え方はVueやFigmaに依存しない。たとえば記事制作なら、調査、執筆、レビューを別の仕事として切れる。
Research Agent
├─ Web research Skill
└─ Source verification Skill
Writing Agent
├─ Writing Skill
└─ Style guide Skill
Review Agent
├─ Fact check Skill
└─ Editorial review Skillデータ分析でも同じだ。
Data Agent
├─ Spreadsheet Skill
└─ SQL Skill
Analysis Agent
├─ Statistics Skill
└─ Visualization Skill
Report Agent
├─ Document Skill
└─ Writing Skill個々のSkill名より、関連するSkillsを1つの仕事としてまとめ、その仕事をどのAgentへ持たせるかという考え方の方が再利用しやすい。
1つのAgentで済ませた方がよい仕事もある
Agentを細かく分ければ常に効率がよくなるわけではない。複数Agentにすると、今度は変更内容や判断結果を次のAgentへ渡す必要があり、同じ情報を読み直すこともある。
次のような仕事なら、1つのAgentで完結させた方が単純だ。
- Skillsが少ない
- 同じ種類の仕事に使う
- 同じコードや資料を共有する
- Toolや権限がほぼ同じ
- 短い作業で完了する
逆に、Skillsが増え続けているのに「便利だから全部このAgentへ入れておく」という状態になってきたら、役割を分ける余地がある。
「何個から分けるか」では決められない
Skillsが10個なら分ける、20個なら多すぎる、といった固定の境界はない。
Skillのdescriptionが長ければメタデータも増えるし、似たSkillが多ければ選択肢の区別も難しくなる。AgentのコンテキストにはAGENTS.md、Tool定義、リポジトリの内容、会話履歴なども入るため、Skill数だけを見ても全体像は分からない。
見るべきなのは、そのAgentが実際に仕事をするときの状態だ。
- 本当にすべてのSkillsが必要か
- 関係のないSkillsまで候補になっていないか
- 似たSkillsが増えて選択しにくくなっていないか
- 仕事ごとに必要なToolや権限が大きく違わないか
- 読む資料や触るコードの範囲を分けられないか
CodexのToken使用量については、別の記事でAGENTS.md、Skills、MCP、Tool結果などが入力へどう影響するかを扱っている。
CodexのTokenは何で決まる？ 入力・推論・出力ごとの節約方法 | kuromica
CodexのToken消費を、モデルへ渡す情報、推論、回答、繰り返し処理に分けて確認します。CLI、AGENTS.md、Skills、MCP、ログ、推論設定など、利用者側で実際に減らせる場所もまとめます。
https://kuromica.com/blog/codex-token-usage-input-reasoning-output/
Skillsを増やすときはAgentの境界も考える
Skillsを使えば、大きな仕事を小さな手順へ分けて再利用できる。ただ、Skillの数だけを増やして1つのAgentへ集め続けると、Agent側では再び大きなコンテキストを抱える構成になっていく。
そこで、関連するSkillsを仕事単位でまとめ、その仕事を担当するAgentへ必要なものだけ持たせる。
大きな仕事
↓
工程へ分ける
↓
必要なSkillsを組み合わせる
↓
担当するAgentを決める
↓
Skills / Tools / 権限を絞る
↓
成果物を次の工程へ渡すこの形なら、Skillは「仕事のやり方」を再利用する単位、Agentは「どの仕事を担当するか」を分ける単位として扱える。
Coordinator
├─ Agent A
│ └─ 関連Skills 2〜3個
├─ Agent B
│ └─ 関連Skills 2〜3個
└─ Agent C
└─ 関連Skills 2〜3個Figma、Vue、Playwrightのような具体的なSkillは、この組み合わせ方を説明する材料にすぎない。Skillsが増えてきたときは、「次に何を追加するか」と同時に、そのSkillをどのAgentが持つべきかまで考えると、コンテキスト、Tool、権限を仕事の境界に合わせやすくなる。
参考資料
OpenAI：Codex agent loop
https://openai.com/ja-JP/index/unrolling-the-codex-agent-loop/
OpenAI：Codex Skills
Build skills | ChatGPT Learn
Give ChatGPT and Codex new capabilities and expertise
https://developers.openai.com/codex/skills
OpenAI：Codex Subagents / Custom Agents
Subagents | ChatGPT Learn
Use subagents in ChatGPT and Codex, and configure custom Codex agents
https://developers.openai.com/codex/subagents
OpenAI：Model guidance
Model guidance | OpenAI API
Compare model features, migration guidance, and prompting best practices across OpenAI models.
https://developers.openai.com/api/docs/guides/latest-model
Agent Skillsの設計
Claude Code・CodexのSkillはこう作る：効果的なSKILL.mdを作る10のポイント | kuromica
Claude CodeやCodexで再利用しやすいAgent Skillの作り方を、すぐ使えるSKILL.mdテンプレートと10の設計ポイント、公式ガイドや実例をもとに解説します。
https://kuromica.com/blog/claude-code-codex-skill-design-10-points/
