AIの種類に依存しないプロジェクト構成｜AGENTS.mdとスキルの正本は1つ

2026.09.06AI活用術

AIを使っていると、この作業はClaude Codeに、この作業はCodexにと切り替えたり、新しいモデルが出て普段使いのAIを乗り換えたりします。

ところが、AIへの指示ファイルやスキルの置き場は、AIエージェントごとにバラバラです。

AIごとに整備するのは面倒ですし、今使っているAIの分だけを整備すると、乗り換えに手間がかかります。

その解決策は、設定の正本を1つにして、他はそこを参照させることです。正本とは「迷ったらここを見る」と決めた1か所のことです。

これでプロジェクトはAIの種類に依存しなくなり、乗り換えも気軽にできます。

この記事では、AIへの指示ファイルとエージェントスキルの正本を1つにする具体的な構成を解説します。

設定の置き場がAIごとに違うから、運用も乗り換えもやりづらい

AIエージェントごとに異なる指示ファイルとスキルの置き場所と、修正のたびに3か所を直す手間

AIエージェントは、プロジェクトに置かれた指示ファイルを読んでから作業し、スキルも決まったフォルダから読み込みます。

指示ファイルとスキルの置き場所は、AIごとに違います。

Claude Code：指示ファイルは CLAUDE.md、スキルは .claude/skills/
Codex：指示ファイルは AGENTS.md、スキルは .agents/skills/
Gemini CLI：指示ファイルは GEMINI.md、スキルは .gemini/skills/（.agents/skills/ も可）

AIごとに設定ファイルを整備すると、同じルールを何度も書くことになります。かといって、今使っているAIの設定ファイルだけを整備すると乗り換えに手間がかかります。

設定ファイルの中身をコピーしてAIごとに置く多重管理も、最初だけは簡単です。しかし修正のたびに、全AI用の設定ファイルを直さなければなりません。

正本を1つにして、ほかは参照させる

複数のAIエージェントが1つの正本を参照する構造

解決策は、設定ファイルの正本を1つにして、AIごとの設定ファイルはその正本を参照させることです。

情報の種類ごとに正本を1つ決め、ほかはそこを参照する考え方はSSoTと呼ばれ、SSoTの解説記事で詳しく紹介しています。AIの設定も、この考え方で整理できます。

正本にするのは、Codexをはじめ多くのAIエージェントが読む AGENTS.md と、スキルのフォルダの2つ。順に見ていきます。

指示の正本はAGENTS.md。CLAUDE.mdは@AGENTS.mdの1行だけ

AGENTS.mdを指示の正本にし、CLAUDE.mdは1行の参照で読み込む構成図

AGENTS.md は、Codexが作業前に必ず読むファイルです。プロジェクトのどこにどんなファイルがあるか、AIがどんなルールに従うべきかを書きます。

いわば、AIの作業マニュアルです。

AGENTS.md はCodex専用ではありません。Linux傘下の団体が管理するオープン形式で、6万超のオープンソースプロジェクトが使っています。

対応するAIエージェントも、Codex、Gemini CLI、Cursor、GitHub Copilotのコーディングエージェントなど多数。

一方、Claude Codeが読むのは CLAUDE.md だけで、AGENTS.md は読みません。そこで CLAUDE.md の中身は、次の1行だけにします。

@AGENTS.md

こう書くと、Claude Codeは AGENTS.md を読み込みます。指示の正本は AGENTS.md だけになり、Claude CodeもCodexも同じ正本を読むようになります。

この書き方は、Claude Codeを開発するAnthropicの公式ドキュメントが案内している方法です。

Claude Codeだけに効かせたい指示があれば、@AGENTS.md の下に書き足せます。

スキルの正本は.agents/skills。Claude Codeからはシンボリックリンク

スキルの正本を.agents/skills/に集約しClaude Codeだけシンボリックリンクで参照する構成図

次はスキルの正本を絞ります。

AIエージェントごとのスキル置き場は以下のとおり。

Codex： .agents/skills/
Claude Code：.claude/skills/
Gemini CLI：.gemini/skills/（.agents/skills/ も可）

そこで、スキルの正本は .agents/skills/ にだけ置きます。CodexとGemini CLIはそのまま読めるので、リンクが要るのはClaude Codeだけです。

.claude/skills/ からは、スキルごとにシンボリックリンクで正本を参照します。

シンボリックリンクは、フォルダのショートカットのような仕組みです。ショートカットを開くと元のフォルダへ移動するのと同じで、リンクの実体は元のフォルダにあります。

プロジェクト
├── .agents/
│   └── skills/
│       └── article-writing/   … スキルの正本
└── .claude/
    └── skills/
        └── article-writing -> … シンボリックリンク

Claude Codeはリンク先のスキルを読むと公式に明記し、Codexもリンク先を読むと明記しています。

正本が1つなら、新しいAIは同じスキルで試して選べる

同じスキルで複数のAIを比較し選ぶ流れ

指示ファイルとスキルの正本を1つにし、ほかは参照させておけば、AIを乗り換えても設定ファイルをいじる必要はありません。

さらに、同じスキルを複数のAIエージェントに使わせ、成果物の品質を比べられます。

ぼくは新しいモデルが出たタイミングで、同じスキルを複数のAIエージェントに使わせ、どのAIを使うべきかを判断しています。

AIに正本の整理を任せる指示文

正本の整理は、以下の指示でAIに任せられます。

このプロジェクトのAIエージェント向け設定を、AIエージェントに依存しない構成に整理して。
1. 指示の正本はAGENTS.mdにし、CLAUDE.mdの中身は「@AGENTS.md」の1行だけにする
2. スキルの正本は.agents/skills/に置き、.claude/skills/からは各スキルへのシンボリックリンクで参照する
3. 片方のAIエージェントでしか動かないスキルと、片方だけに効かせたい指示はそのまま残す

まとめの前に、お知らせを。

無料メルマガで実務で使えるAI活用を毎日配信中。1分で登録できます。