Claude Code と Codex を併用し始めると、指示ファイルは AGENTS.md に一本化できても、.claude/agents/ に溜めた subagent と .claude/skills/ の skill は Codex から読まれません。Codex 側に同じものを書き直すと、片方の定義だけを直し、もう片方のツールは古い手順のまま作業する、という状態が生まれます。
本記事は、併用を決めたあとの設定の共有に絞ります。Codex の /import での取り込み、skill の置き場所の一本化、subagent の二重定義の 3 つから、自分の構成に合う方法を選べるように整理します。どちらのツールをどの作業に使うかは Claude Code と Codex の実務比較 を参照してください。
仕様は 2026 年 9 月 25 日に確認した公式ドキュメントに基づきます。公式に記載が無く、手元で確かめただけの挙動は、その都度明記して分けます。
結論 — そのまま共有できるもの、変換が要るもの
指示・skill・subagent の 3 種類で、共有のしかたが分かれます。
| 資産 | Claude Code の置き場所 | Codex の置き場所 | 共有のしかた |
|---|---|---|---|
| 指示 | CLAUDE.md または AGENTS.md | AGENTS.md | AGENTS.md 1 本で共有できる |
| skill | .claude/skills/<skill-name>/SKILL.md | .agents/skills/<skill-name>/SKILL.md | 形式は同じ。置き場所と必須項目をそろえれば共有できる |
| subagent | .claude/agents/*.md (Markdown) | .codex/agents/*.toml (TOML) | 形式が違うため変換が要る |
最初の一手は、Codex 側で /import を実行して既存の Claude Code の設定を一度取り込み、そのうえで以後どちらを正本にするかを決めることです。取り込んでも元の Claude Code の設定ファイルは変更されないため、試してから方針を決められます。ただし AGENTS.md を両方で共有している場合は、取り込み後に AGENTS.md の差分を確かめてください。取り込み先の AGENTS.md を上書きするか追記するかは、公式ドキュメントに記載がありません。
AGENTS.md でそろうのは指示だけ
Claude Code は v2.1.277 から AGENTS.md を直接読むようになりました。既定では CLAUDE.md 系のファイルが無い場合に AGENTS.md を読みます。読み込みの判定と /config の設定は Claude Code の AGENTS.md 対応の記事 で詳しく扱っています。
一方で Claude Code のメモリ仕様 は、読まないものとして AGENTS.local.md・AGENTS.override.md と「.agents/ ディレクトリ配下のすべて」を挙げています。Codex が skill を探す .agents/skills/ は、Claude Code から見ると読み込みの対象外です。
skill の手順を AGENTS.md に書き写せば両方に伝わりますが、毎回の会話で全文が読まれることになります。必要な場面でだけ本文を読み込むという skill の性質は失われます。
FIXIT指示ファイルは 1 本にしたのに、Codex だといつもの手順が出てこないの？
Hayateはい。AGENTS.md でそろうのは指示だけです。skill と subagent は置き場所が違うので、別の手当てが要ります。
置き場所と形式の違い
skill と subagent について、2 つのツールの仕様を並べます。出典は Claude Code の skills・subagents、Codex の Build skills・Subagents です。
| 項目 | Claude Code | Codex |
|---|---|---|
| skill の置き場所 (リポジトリ) | .claude/skills/<skill-name>/ | 現在地からリポジトリのルートまで、各階層の .agents/skills/ |
| skill の置き場所 (ユーザー) | ~/.claude/skills/ | ~/.agents/skills/ |
| SKILL.md の必須項目 | なし (name を省くとディレクトリ名になる) | name・description |
| skill の呼び出し | 自動、または /skill-name で直接 | 自動、または $ か /skills で指定 |
| subagent の置き場所 (リポジトリ) | .claude/agents/ (サブフォルダも読む) | .codex/agents/ |
| subagent の置き場所 (ユーザー) | ~/.claude/agents/ | ~/.codex/agents/ |
| subagent の形式 | YAML frontmatter 付きの Markdown | 1 ファイルに 1 エージェントを書く TOML |
| subagent の必須項目 | name・description | name・description・developer_instructions |
| subagent の呼び出し | description に合う作業を自動で委任 | 直接の依頼、またはプロジェクトや skill の指示による委任 |
skill は両ツールとも Agent Skills のオープン標準に基づいており、SKILL.md の形式は共通です。主な違いは置き場所で、必須項目の差 (後述) を押さえれば共有できます。
解説記事によっては ~/.codex/skills を Codex の skill の置き場所としているものがあります。現在の Codex の公式ドキュメントが挙げるのは .agents/skills と ~/.agents/skills (ほかに管理者用の /etc/codex/skills) です。なお、Gemini CLI の後継の Antigravity CLI も .agents/skills/ を使います。移行の経緯は Gemini CLI から Antigravity CLI への移行手順 にまとめています。
方法を選ぶ — 取り込み・置き場所の一本化・二重定義
公式仕様を踏まえると、共有の方法は取り込み・置き場所の一本化・二重定義の 3 つに分かれます。二重定義は、手でそろえるか生成するかでさらに 2 通りあります。どれを選ぶかは、どちらのツールが主か、skill と subagent がどれだけあるか、どれくらいの頻度で直すかで決まります。次の表は本記事の提案です。
| チームの状況 | 選ぶ方法 | 理由 |
|---|---|---|
| Claude Code が主で、Codex は特定の作業にだけ使う | /import で 1 回取り込む | Codex 側を直す頻度が低い |
| 両方を日常的に使い、skill が多い | skill の正本を .agents/skills/ に置き、Claude Code からリンク | 同じ SKILL.md を 2 か所で直さずに済む |
| subagent が数本で、役割をあまり変えない | 二重定義 (手でそろえる): 両方に定義し、本文だけそろえる | 変換の仕組みを作るより、手でそろえるほうが安い |
| subagent が多く、頻繁に直す | 二重定義 (生成する): Markdown を正本にして TOML を生成し、CI で差分を検査する | 片方だけ古い状態を機械で検出できる |
3 つは組み合わせて使えます。たとえば /import で一度取り込んでから、skill だけを .agents/skills/ に寄せ、subagent は両方に定義する構成も取れます。
Codex の /import で取り込む
Codex には、ほかのエージェントの設定を取り込む機能があります。手で変換を始める前に、まずこれで済むかを確かめてください。
取り込まれるもの
Codex の Import from another agent が挙げる対応は次のとおりです。
| Claude Code 側 | Codex 側での取り込み先 |
|---|---|
| 指示ファイル | AGENTS.md |
settings.json | config.toml |
| Skills | Skills |
| スラッシュコマンド | Skills |
| Subagents | Codex の subagents |
| MCP の設定 | Codex の MCP の設定 |
| Hooks | Codex の hooks |
このほか、プラグイン、プロジェクト、プロジェクトのメモリ、直近 30 日のチャットも対象です。これらがデスクトップアプリと CLI のどちらでも取り込めるかは、公式ドキュメントで区別されていません。公式ドキュメントは、取り込んでも既存のエージェントの設定は変更・削除されないと明記しています。
実行する場所と使えない場面
Codex CLI では、ローカルの対話セッションで /import と入力します。実行中のタスクがあるとき、リモートセッション、ローカルの app-server デーモンに接続しているときは使えません (CLI のスラッシュコマンド一覧)。
ChatGPT デスクトップアプリからも取り込めます。取り込み元は、デスクトップアプリが Claude Code・Claude Cowork・Cursor、Codex CLI が Claude Code・Cursor です。元のエージェントと同期を保つ自動更新は、デスクトップアプリの機能として案内されています。Codex CLI の /import に継続的な同期があるかは、公式ドキュメントに記載が見当たりません。CLI で取り込んだ場合は 1 回限りの取り込みとして扱い、以後の正本を決めておくほうが安全です。
取り込んだ後に見直す項目
公式ドキュメントは、取り込み後に見直す項目として次を挙げています。
- skill と agent に付けていたツールの制限や権限
- 独自の認証を使う MCP サーバーの設定
- 挙動が変わりうる hooks
- 手作業での対応が要るプラグイン
- 引数・シェル展開・ファイルパスのプレースホルダーに依存するプロンプトやコマンド
注意
Claude Code の subagent に付けた tools や permissionMode が、取り込み後の
TOML
でどう表されるかは公式ドキュメントに記載が無く、本記事でも確かめていません。取り込んだら、生成された
.codex/agents/*.toml を開いて、権限が意図どおりかを必ず確認してください。
skill を .agents/skills にまとめる
両方のツールを日常的に使うなら、skill の実体を 1 か所に置き、もう一方のツールの置き場所からはリンクで参照します。
正本を .agents/skills に置く理由
Codex は .agents/skills/ を読み、Claude Code は .claude/skills/ を読みます。どちらを実体にしてもリンクは張れますが、本記事は .agents/skills/ を正本にする構成を勧めます。特定のツール名を含まない場所で、Antigravity CLI など Codex 以外のツールも読むためです。Claude Code 側は .claude/skills/ にリンクを置くだけで済みます。
skill ごとにリンクするか、ディレクトリごとにリンクするか
リンクの張り方は 2 通りあります。相対パスは、リンクを置いたディレクトリを起点に解決されます。
# skill ごとにリンクする (Claude Code の公式ドキュメントに記載がある方法)
mkdir -p .claude/skills
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes
# .claude/skills ディレクトリごとにリンクする (公式に記載は無い)
ln -s ../.agents/skills .claude/skills| 方法 | Claude Code の公式ドキュメント | 向く場面 | 注意すること |
|---|---|---|---|
| skill ごとのリンク | 記載あり | 共有する skill を選びたい | skill を足すたびにリンクも足す |
| ディレクトリごとのリンク | 記載なし | すべての skill を両方で使う | Claude Code 専用の skill を置けない |
Claude Code の公式ドキュメントには「<skill-name> の項目は、ディスク上の別のディレクトリへのシンボリックリンクにできる」とあります。認められているのは skill フォルダ単位のリンクです。Codex も skill フォルダのシンボリックリンクをたどると明記しています。
ディレクトリごとのリンクについては、手元で確かめた挙動です。2026 年 9 月 25 日に macOS・Claude Code 2.1.281 で、.agents/skills/ に置いた skill を .claude/skills ごとのリンク経由で読み込めました。リンクを消すと、同じ skill は見つかりませんでした。変更履歴には .claude/skills がシンボリックリンクの場合に Linux のサンドボックスが起動しない不具合の修正 (v2.1.178) があり、この構成で使われていることはうかがえます。ただし、サポートを約束する記載ではありません。チームに広げるなら skill ごとのリンクが無難です。
Windows のメンバーがいる場合
Claude Code のメモリ仕様は、CLAUDE.md をシンボリックリンクにする場合の注意として、Windows ではリンクの作成に管理者権限か開発者モードが要ること、Git は core.symlinks が無効だとリンクを 1 行のテキストファイルとして取り出すことを挙げています。この条件に当たるメンバーの環境では、リンクが 1 行のテキストファイルになるため、skill は読み込まれない状態になります。
Windows ネイティブ環境でリンク経由の skill の読み込みは確かめていません。Windows のメンバーがいるチームでは、リンクを使わずに /import で取り込むか、skill をコピーして両方に置き、内容の一致を CI で検査する方法も候補になります。
SKILL.md を両方で通る形にする
形式が共通とはいえ、必須項目と拡張項目の扱いは 2 つのツールで違います。共有する SKILL.md は、次の条件を満たす形で書いてください。
まず、name と description を必ず書きます。Claude Code では省略できますが、Codex では必須です。name は Agent Skills 仕様に合わせ、小文字の英数字とハイフンだけで 64 字以内にし、親ディレクトリ名と一致させます。
---
name: release-notes
description: マージ済みの PR からリリースノートの下書きを作る。利用者に見える変更点だけを抜き出したいときに使う。
---
## 手順
1. 前回のリリースタグ以降にマージされた PR を一覧にする
2. 利用者に見える変更だけを残し、内部のリファクタリングは除く
3. 追加・変更・修正の 3 つに分けて下書きを書く次に、Claude Code 固有の項目 (disable-model-invocation・context・agent など) と、Agent Skills 仕様の任意項目で実装ごとに扱いが違う allowed-tools の扱いです。手元の codex-cli 0.156.1 では、disable-model-invocation・allowed-tools・context: fork を含む SKILL.md も skill 一覧に載り、読み込みエラーにはなりませんでした。ただし、Codex がこれらを解釈するとは公式に書かれていません。たとえば context: fork が Codex で Claude Code と同じ扱いになる保証はありません。挙動をこれらの項目に頼る skill は .claude/skills/ にだけ置き、共有する skill から外してください。
最後に、description は要点を先頭に置きます。Claude Code は description と when_to_use の合計を skill 一覧で 1,536 字に切り詰め、Codex は skill 一覧全体を文脈の 2% (文脈の大きさが不明なときは 8,000 字) に収めます。どちらでも後半が読まれない場合があります。
skill の中身の書き方と、チームで属人化させない運用は Agent Skills の共有設計 で扱っています。
subagent は形式を変換して両方に置く
subagent は形式が違うため、リンクでは共有できません。項目の対応を押さえたうえで、両方に定義します。
項目の対応表
Claude Code の subagent の frontmatter と、Codex の custom agent のファイル形式 を突き合わせると、次のようになります。
Claude Code (.claude/agents/*.md) | Codex (.codex/agents/*.toml) | 移すときの扱い |
|---|---|---|
name | name | 同じ値にする |
description | description | 同じ値にする |
| frontmatter の下の本文 | developer_instructions | 本文をそのまま入れる |
model | model | 値をそれぞれのモデル名に書き換える |
effort | model_reasoning_effort | 取りうる値を確かめて書き直す |
mcpServers | mcp_servers | 各ツールの書式に合わせて書き直す |
tools・disallowedTools | 対応する項目なし | 書き込みを禁じたいなら sandbox_mode で制限する |
permissionMode・hooks・memory など | 対応する項目なし | 移さない |
skills (起動時に skill の本文を注入する) | skills.config (skill の有効・無効) | 名前が似ているが意味が違う |
Codex では、custom agent に書かなかった sandbox_mode・mcp_servers・skills.config は親のセッションから引き継がれます。レビュー役のように書き込ませたくない agent は、Codex 側で sandbox_mode を明示してください。
name = "reviewer"
description = "変更差分をレビューし、バグと規約違反を指摘する。コードを変更した直後に使う。"
sandbox_mode = "read-only"
developer_instructions = """
あなたはコードレビュー担当です。親から渡された変更差分を読み、バグ・規約違反・テストの不足を指摘してください。
コードは書き換えず、指摘と根拠だけを返してください。
"""Claude Code 側では、同じ役割を次のように書きます。書き込みの制限は tools で表します。
---
name: reviewer
description: 変更差分をレビューし、バグと規約違反を指摘する。コードを変更した直後に使う。
tools: Read, Grep, Glob
---
あなたはコードレビュー担当です。親から渡された変更差分を読み、バグ・規約違反・テストの不足を指摘してください。
コードは書き換えず、指摘と根拠だけを返してください。呼び出され方の違い
Claude Code は、subagent の description を見て、合う作業を自動で委任します。Codex の公式ドキュメントは、ローカルの Codex について「直接の依頼か、該当するプロジェクトや skill の指示があったときにエージェントを起動する」と説明しています。description を見て自動で委任するという記載はないため、.codex/agents/ に置いただけで Claude Code と同じように呼ばれるとは考えないほうが安全です。
Codex で custom agent を使わせたい作業は、AGENTS.md に「コードを変更したら reviewer にレビューを依頼する」のように書いておきます。Claude Code が AGENTS.md を読む構成なら、両方のツールで agent の name をそろえておくと、AGENTS.md の同じ一文が Claude Code と Codex のどちらにも通じます。
FIXITじゃあ Codex の subagent は、置いただけだと呼ばれないってこと？
Hayate公式に自動で呼ぶという記載はありません。使う場面を AGENTS.md に書いておくのが早いです。
本文を二重に持たないための工夫
subagent を両方に定義すると、役割の説明が 2 か所に分かれます。片方だけ直す事故を防ぐ方法として、一般的には次の 2 つがあります。
- 役割の説明を Markdown の 1 ファイルにまとめ、そこから Codex 用の TOML を生成する。生成結果とリポジトリの TOML に差分があれば CI で落とす
- 役割の説明を共通のドキュメントに置き、両方の定義からは「作業前にそのファイルを読む」とだけ書く
TOML を生成する方法は差分を機械で検出できます。共通のドキュメントを読ませる方法は仕組みが要らない代わりに、読み込みを agent の判断に任せることになります。Codex の公式ドキュメントは custom agent の形式について「作成と共有の仕組みが成熟するにつれて変わりうる」と書いているため、生成の仕組みを作るなら形式の変更に合わせて直す前提で考えてください。どの役割を subagent に切り出すかは Claude Code の subagent 設計パターン を参照してください。
両方で読み込まれたかを確かめる
共有の仕組みを作ったら、両方のツールで実際に読み込まれたかを確かめます。確認の手段は次のとおりです。
| 確認するもの | Claude Code | Codex |
|---|---|---|
| skill | / の一覧に出るか、/skill-name で直接呼べるか | /skills の一覧か、$ の候補に出るか |
| subagent | 委任したときの表示にエージェント名が出るか | 名前を指定して起動を頼み、/agent でスレッドを確かめる |
| 反映されないとき | 新しく agents ディレクトリを作った場合は再起動する | skill の変更が自動で検出されないときは再起動する |
Codex は、同じ名前の skill が複数の場所にあっても統合せず、両方を選択肢に出します。~/.agents/skills/ とリポジトリの .agents/skills/ に同じ skill を置くと、どちらが使われたか分かりにくくなるため、置き場所はどちらか一方に決めてください。
コツ
確認の手順は、共有の仕組みと一緒にチームの手順書へ入れておくと、新しく参加したメンバーの環境でも同じように確かめられます。特にシンボリックリンクを使う構成では、Windows のメンバーの環境で読み込めるかを最初に確認してください。
共有の方法は、読み込みの確認までをセットで決める
進め方は、まず Codex の /import で一度取り込み、その結果を見てから正本を決める順番です。skill は .agents/skills/ を正本にしてリンクでつなぎ、subagent は項目の対応を押さえて両方に定義します。どの方法を選んでも、両方のツールで読み込まれたことを確かめるところまでを手順に含めてください。
Codex の custom agent の形式は変わりうると公式が書いており、Claude Code も更新の頻度が高いツールです。共有の仕組みを作ったあとも、両ツールの変更履歴で skill と subagent に関わる変更を追い、確認の手順を定期的に回すと、片方だけ古い設定が残る状態を早めに見つけられます。
AI 開発ツールの運用ルールを整えたい方へ
AI 駆動開発のクリエイティブスタジオである FIXIT は、複数の AI 開発ツールを併用するチームの運用設計を支援しています。AI 開発ツール定着支援 では、ツールの選定から、チームで共有する規約・skill・subagent の置き場所と確認手順づくりまでを支援しています。複数のツールに分かれた設定を整理したい方は、お問い合わせ から現在の構成をお聞かせください。