SKILL.md と AGENTS.md の違い：それぞれに何を書くか

並べて比べる

agents.md、Codex と Claude Code のドキュメント、Agent Skills の仕様（2026 年 11 月 5 日に確認）にもとづきます。

例：ふくらんだ 1 ファイルを分ける

架空の例です。9 人のプロダクトチームの AGENTS.md が 400 行にふくらんでいました。テストのコマンドと命名規則に加えて、リリースノートの 120 行の手順と、データベースのマイグレーションの 90 行のチェックリストが入っていたのです。エージェントは、リリースとは関係のない多くの作業でも、毎回これを全部読んでいました。

• AGENTS.md に残した（60 行）：ビルドとテストのコマンド、フォルダの構成、命名規則、「秘密情報はコミットしない」。
• リリースノートのスキルに移した：手順。説明は「リリースノートや顧客向けの変更履歴を頼まれたときに使う」。
• マイグレーションのレビューのスキルに移した：チェックリスト。説明は「データベースのマイグレーションを追加・変更する変更のときに使う」。

チームで Claude Code を使う人は、CLAUDE.md に @AGENTS.md の 1 行を足し、どちらのツールも同じ常設のルールを読むようにしました。いまは毎回のセッションが 60 行で始まり、2 つの手順は頼まれたときだけ読み込まれます。

自分のファイルを分ける

1. AGENTS.md を読み、各節に「どの作業でも」か「1 つの作業」かの印をつける。
2. 「どの作業でも」の節は短く保つ：コマンド、規約、構成、絶対のルール。
3. 「1 つの作業」の節は、それぞれスキルにする。名前と「〜のときに使う」の説明をつける。
4. チームで両方のツールを使うなら、CLAUDE.md のインポートで Claude Code にも AGENTS.md を読ませる。
5. 試す：それぞれの作業をふつうの言葉で頼み、正しいスキルが読み込まれるかを確かめる。

次の一歩：スキルを共有する

1 つのリポジトリのスキルは、そこで作業する人にしか届きません。チーム全体が複数のリポジトリやツールで使うスキルは、GitHub で Claude スキルを共有するとClaude Code、Codex、Cursor、OpenCode でスキルをそろえるを参照してください。

よくある質問

SKILL.md と AGENTS.md の違いは？

AGENTS.md は、リポジトリでコーディングエージェントが毎回のセッションの最初に読む常設の指示です。ビルドやテストのしかた、プロジェクトの規約を書きます。SKILL.md はリリースノートを書くといった 1 つの作業の手順で、依頼がその説明に合ったときだけ読み込まれます。毎回必要な事実は AGENTS.md に、1 つの作業の手順はスキルに書きます。

Claude Code は AGENTS.md を読む？

読みます。Claude Code のドキュメントによると、作業ディレクトリかその上に CLAUDE.md がないとき、リポジトリの AGENTS.md をプロジェクトの指示として読みます。CLAUDE.md から AGENTS.md をインポートすれば、両方のツールで 1 つのファイルを共有できます。

スキルで AGENTS.md を置き換えられる？

できません。スキルはその作業のときにしか読み込まれないので、テストのコマンドや命名規則のように毎回守るべきルールが抜けてしまいます。そうしたルールは AGENTS.md に残し、手順が何段階もあるものだけをスキルに移します。