AGENTS.mdとは？CLAUDE.md・SKILL.mdとの違いと、どのAIツールがどれを読むのか

AIコーディングツールを試そうとリポジトリを開いたら、AGENTS.md という見慣れないファイルが置いてある。そんな場面があります。

開いてみると中身はただの文章で、プログラムには見えません。README とも別物のようです。

調べていくと CLAUDE.md や SKILL.md も出てきます。似た名前が3つ並び、どれを自分が書けばいいのか分かりません。

この記事では、3つが何のためのファイルなのか、どのAIツールがどれを読むのか、そして自分は何を書けばよいのかを、各社の公式ドキュメントの記述から整理します。

AGENTS.mdとは、AIエージェント向けのREADMEのこと

AGENTS.md は、AIコーディングツールに向けて、そのプロジェクトの事情と指示を書いておくファイルです。

公式サイトの agents.md は、この形式を コーディングエージェントを導くための、単純で開かれた形式 だと説明しています。

同じページは、もっと短い言い方もしています。エージェント向けのREADMEです。

READMEが人間に向けて「このプロジェクトは何で、どう動かすか」を書く場所なら、AGENTS.md はそれをAI向けに書く場所、という対比です。

中身の決まりはありません。

公式サイトは「AGENTS.md は標準のMarkdownそのものです。好きな見出しを使ってください」と書いています。

決まっているのはファイル名と置き場所だけで、書く項目のスキーマは定義されていません。

拡張子の .md は、Markdown という文章の書き方を表します。ファイルそのものの開き方は.mdファイル、記法のほうはマークダウン記法の記事で扱いました。

誰が決めている形式なのかも、はっきりしています。

公式サイトは「AGENTS.md は現在、Linux Foundation 傘下の Agentic AI Foundation によって管理されています」と書いています。1社の独自仕様ではありません。

規模についても記述があります。同じページは 6万を超えるオープンソースプロジェクトで使われている としています。

CLAUDE.md・SKILL.mdとは、役割がどう違うのか

3つを並べると、次のようになります。

	AGENTS.md	CLAUDE.md	SKILL.md
何を書くファイルか	プロジェクトの事情と指示	プロジェクトの事情と指示	ひとつの手順のまとめ
誰が決めた形式か	Agentic AI Foundation（Linux Foundation）	Anthropic	agentskills.io（Anthropicが開発しオープン化）
形式の決まり	なし。標準のMarkdown	なし。Markdown	フォルダ＋SKILL.md。オープン形式では最低限 name と description
いつ読まれるか	読みに来るツールが決める	ツールを起動するたび、毎回	起動時は名前と説明だけ。本文は必要になったときだけ

表を縦に見ると、分かれ目が1か所しかありません。

AGENTS.md と CLAUDE.md は、どちらもプロジェクトの事情と指示を継続的に渡すファイルです。書く内容は同じ系統で、違うのはどのツールが探しに来るかです。

役割が違うのは SKILL.md だけです。ここが3つを混乱させている正体だと考えます。

なお、この整理は本記事の読み取りです。どの公式ドキュメントも、3つをこの形で並べてはいません。

AGENTS.md の欄だけ、いつ読まれるかが書けません。

AGENTS.md はファイルの形式を決めたもので、読み込みの手順までは決めていないからです。

いつどう読むかは、読みに来るツールごとの規則になります。次の章で見ます。

SKILL.md が別物である根拠は、読み込みのタイミングにあります。

Claude Code の公式ドキュメントは、CLAUDE.md の内容とは違い、スキルの本文は使われるときにだけ読み込まれる と書いています。

agentskills.io は、この読み込みを3段階の「段階的開示」として説明しています。起動時に読まれるのは各スキルの名前と説明だけです。

つまり CLAUDE.md は「常に持たせておく事実」、SKILL.md は「必要になったら開く手順書」です。

ここで1つ、注意点を書いておきます。

SKILL.md に必ず書く項目は、形式そのものの決まりと、個々の製品の決まりとで書き方が違います。

agentskills.io は名前と説明を最低限としていますが、Claude Code の公式ドキュメントは全項目が任意で説明だけを推奨としています。

ある製品での挙動を、形式そのものの決まりだと読み違えないでください。この記事で扱う3つとも、同じ注意が要ります。

Skill そのものの仕組みはAgent Skillsの記事で詳しく扱いました。本記事では3つの違いだけを扱います。

どのAIツールが、どのファイルを読むのか

ここが、この記事でいちばん知りたいところだと思います。

主要な5つのツールについて、各社の公式ドキュメントに書かれていることを並べます。

ツール	既定で探す指示ファイル	複数あるとき
Codex（OpenAI）	AGENTS.override.md、次に AGENTS.md	連結する。近いほうが先の指示を上書きする
Claude Code（Anthropic）	CLAUDE.md	連結する。上書きではない
GitHub Copilot	AGENTS.md / CLAUDE.md / GEMINI.md	いちばん近い AGENTS.md が優先される
Cursor	AGENTS.md（リポジトリ直下と下の階層）	記述を確認できていない
Gemini CLI	GEMINI.md（設定で AGENTS.md も指定可）	3階層すべてを連結する

この表から読み取れることが3つあります。

1つ目は、AGENTS.md を1枚置けば多くをまかなえることです。

Codex・GitHub Copilot・Cursor は、いずれも AGENTS.md という名前を既定で探します。

GitHub Copilot の公式ドキュメントは、エージェント向けの指示を AGENTS.md、CLAUDE.md、GEMINI.md という名前のファイルで指定する と書いています。3つとも受け付けます。

ただし同じページは、これらが 現時点ではすべての Copilot 機能で対応しているわけではない とも書いています。

2つ目は、既定の名前が AGENTS.md ではないツールが2つあることです。

Claude Code と Gemini CLI です。ただし Gemini CLI は、設定を書けば AGENTS.md も読むようにできます。

設定で変えられないのは Claude Code だけです。次の章で扱います。

3つ目は、複数あるときの扱いについて、各社の書き方が揃っていないことです。

Codex の公式ドキュメントは「ルートから下へファイルを連結し、空行でつなぐ。現在地に近いファイルのほうが後に来るため、先の指示を上書きする」と書いています。

Claude Code の公式ドキュメントは、言い方が違います。「見つかったファイルはすべて連結される。互いに上書きするのではない」としたうえで、近いほうが後に読まれると説明しています。

GitHub Copilot の公式ドキュメントは、AGENTS.md を リポジトリ内のどこにでも置ける としたうえで、フォルダの階層でいちばん近い AGENTS.md が優先される と書いています。

上書きする、上書きではない、優先される。3社で言葉が揃っていません。

上の階層に置いた指示が実際に効くかどうかは、使うツールごとに確かめる必要がある、ということです。

なお、この3つを並べた比較は本記事の読み取りで、各社は自社の規則だけを書いています。ある社の書き方を、別の社にそのまま当てはめないでください。

表はいずれも2026年9月19日に各社の公式ドキュメントで確認した時点のものです。対応するファイル名は増減します。

どのツールを使うか自体を決めかねている場合は、Claude CodeとCodexの比較の記事が出発点になります。

AGENTS.mdを置いたのに読まれないのは、なぜか

リポジトリに AGENTS.md を置いたのに、Claude Code が指示どおりに動かない。これは設定ミスではありません。

Claude Code の公式ドキュメントに、1文で書かれています。

Claude Code reads CLAUDE.md, not AGENTS.md.

Claude Code は CLAUDE.md を読み、AGENTS.md は読まない という意味です。

回避策も同じページに書かれています。2つあります。

1つ目は、取り込みを使う方法です。CLAUDE.md を作り、その中に AGENTS.md を取り込む1行だけを書きます。

公式ドキュメントは、この形にしておけば 両方のツールが同じ指示を読むようになり、内容を二重に持たなくて済む と説明しています。取り込みの下に Claude Code 向けの指示を書き足すこともできます。

2つ目は、CLAUDE.md を AGENTS.md の別名にしてしまう方法です。同じ中身を別の名前でも開けるようにする、シンボリックリンクという仕組みを使います。

Claude Code 固有の内容を足す必要がなければ、これで足ります。

ただし公式は、Windows では管理者権限か開発者モードが要るため、取り込みのほうを使うよう案内しています。

この章から持ち帰ってほしいのは、手順そのものではありません。

「読んでくれない」と感じたら、まずそのツールが探しているファイル名を公式ドキュメントで確認するという順番です。

名前が合っていないだけ、という場合がかなりあります。

何を書いて、何を書かないのか

形式が自由なぶん、何を書くかで迷います。ここは公式ドキュメントの記述がそのまま使えます。

Claude Code の公式ドキュメントは、CLAUDE.md を 本来なら毎回説明し直すことになる内容を書き留めておく場所 だと位置づけています。

同じページは、書き足すきっかけを4つ挙げています。

• Claude が同じ間違いを2度した
• コードレビューで、知っていてほしかったことを指摘された
• 前回ツールを使ったときと同じ訂正や補足を、また入力した
• 新しく入る人なら同じ説明が要るはずの内容だった

逆に、書かないほうがよいものも書かれています。

公式ドキュメントは、複数手順の作業や、コードベースの一部にしか関係しない内容は、スキルか、対象範囲を限定したルールへ移すよう 案内しています。

手順は SKILL.md 側の持ち場だ、ということです。3つのファイルの分かれ目と、そのまま重なります。

分量の上限は実在します。ここが読者にとっていちばん実務的です。

Codex の公式ドキュメントは、合計サイズが上限に達した時点で、以降のファイルを追加しない と書いています。上限は設定で変えられ、既定は32 KiB（およそ3万3千バイト）です。

置いたファイルが全部読まれるとは限らない、ということです。

Claude Code のほうは、1ファイル200行未満を目安 としています。公式ドキュメントは、長いファイルはコンテキストを多く消費し、指示への追従も下がると説明しています。

毎回読まれるということは、毎回その分だけ読める量を使うということです。この上限の考え方はコンテキストウィンドウの記事で扱いました。

もうひとつ、誤解しやすい点を書いておきます。

これらのファイルは、設定ファイルではありません。Claude Code の公式ドキュメントは、強制される設定ではなく文脈として扱われる と明記しています。

同じページは、CLAUDE.md の内容が システムプロンプトの一部としてではなく、システムプロンプトの後のユーザーメッセージとして渡される とも書いています。

書けば必ず守られる、というものではありません。あらかじめ設定しておく指示という考え方そのものはシステムプロンプトの記事で扱いました。

似た名前のファイルは、どこまで気にすればいいのか

似た名前のファイルは他にもありますが、いま気にする必要があるのは、次の3つだけです。

README.md は人間向けのままで問題ありません。AGENTS.md の公式サイトが自らを「エージェント向けの README」と呼ぶのは、この対比があるからです。

llms.txt は対象が違います。Webサイトの側をAIに読ませるための案内で、リポジトリの中の指示ではありません。

詳しくはllms.txtの記事にあります。

DESIGN.md には、2つの注意が要ります。

ひとつは、同じ名前が別の意味で使われていることです。設計の意図を書き残すという慣例的な呼び方と、Google Labs が公開している形式の仕様が、同じ名前で並んでいます。

もうひとつは、その仕様がまだ動いていることです。

説明文は、DESIGN.md を デザインの見た目をコーディングエージェントへ伝えるための形式仕様 だとしたうえで、版が alpha であること、そして「形式は成熟につれて変わると考えてほしい」ことを明記しています。

ファイル名が付いているだけでは、標準とは限りません。この判断は、DESIGN.md だけの話ではありません。

Google のUI生成そのものはGoogle Stitchの使い方の記事で扱いました。

最初に何を置けばよいのか

判断の順番は3つです。

使っているツールが1つなら、そのツールが探すファイル名で1枚だけ置きます。Claude Code だけなら CLAUDE.md、Codex だけなら AGENTS.md です。

複数のツールを使うなら、AGENTS.md を1枚置きます。Codex・GitHub Copilot・Cursor はこれで読みます。

そのうえで Claude Code も使うなら、AGENTS.md を取り込む1行を書いた CLAUDE.md を足します。内容を二重に持たずに済む形です。

Gemini CLI も使うなら、AGENTS.md を読むように設定で指定します。

手順が増えてきたら、SKILL.md へ切り出します。毎回は要らないが、特定の作業のときだけ要る内容が対象です。

中身は、いきなり網羅しなくて構いません。同じ説明を2回入力したときに1行足す、という積み上げ方が公式の案内にも合っています。

最後に、この記事の限界を書いておきます。

内容はすべて、2026年9月19日に各社の公式ドキュメントを確認した時点のものです。手元で実際の挙動を再現して確かめたわけではありません。

この領域は仕様が速く動きます。実際、Claude Code の公式ドキュメントは1ページの中で、バージョンを10種類ほど引きながら、挙動が変わった箇所を注記しています。

確認したのは5つのツールだけです。agents.md も agentskills.io も、これよりずっと多くの対応製品を掲載しています。

本記事はその一部しか当たっていません。

ですから、ファイル名と置き場所は、使っているツールの公式ドキュメントで都度確認してください。この記事は最初の地図として使ってもらえれば十分です。

社内でAIコーディングツールを配るときのルールづくりを相談したい場合は、お問い合わせからご連絡ください。

この記事の出典

• AGENTS.md（Agentic AI Foundation、2026-09-19確認）
• AGENTS.md（Codex）（OpenAI、2026-09-19確認）
• How Claude remembers your project（Anthropic、2026-09-19確認）
• Skills（Anthropic、2026-09-19確認）
• Agent Skills Overview（agentskills.io、2026-09-19確認）
• Customizing responses with custom instructions（GitHub、2026-09-19確認）
• Adding repository custom instructions for GitHub Copilot（GitHub、2026-09-19確認）
• Rules（Cursor、2026-09-19確認）
• Provide context with GEMINI.md files（Google、2026-09-19確認）
• google-labs-code/design.md（Google Labs、2026-09-19確認）