Skillsと指示ファイルの使い分け：CLAUDE.md・AGENTS.mdに書く内容と共通ルールの管理
この記事で学べること
- Skillsと初期指示ファイルの役割、読み込まれるタイミングの違い
- CLAUDE.mdやAGENTS.mdに書く内容を決める基準
- Markdownの指示だけでは防げない操作と、複数のAIで共通ルールを管理する方法
Skillsと初期指示ファイルの役割
AIに作業を任せるとき、毎回必要な前提と、特定の作業でだけ使う手順を同じファイルに詰め込むと、指示が長くなり、更新もしづらくなります。
この2つを分ける基準は、いつ、どの作業で必要になる情報かです。プロジェクト全体の方針や注意事項は、作業開始時に読む初期指示ファイルへ置きます。ブログ執筆や障害調査など、特定の作業に必要な手順はSkillへまとめます。Skillは、AIが必要に応じて読み込む指示や資料のまとまりです。
このサイトでは、Claude CodeとCodexに渡す指示を、読み込むタイミングと適用する作業範囲に沿って管理しています。
ただし、どちらの文書も、操作を必ず制限する仕組みではありません。秘密情報へのアクセスや危険なコマンドの実行を防ぐ必要がある場合は、文書による指示に加えて、権限設定や自動検査を使います。
この記事では、各製品が読むファイルの違いを整理したうえで、指示の置き場所、操作を制限する仕組み、複数のAIでの共通ルール管理を説明します。
読み込むタイミングの違い
初期指示ファイルとSkillsは、主に次のように使い分けます。
| 種類 | 役割 | ファイルの例 |
|---|---|---|
| 初期指示ファイル | プロジェクトの前提、方針、注意事項、検証コマンドを作業開始時から伝える | CLAUDE.md、AGENTS.md、GEMINI.md、.github/copilot-instructions.md |
| Skills | 特定の作業に必要な手順、専門的なワークフロー、参考資料、スクリプトを必要なときに渡す | SKILL.md |
全作業で必要な短いルールは初期指示ファイルへ、特定の作業でだけ使う詳しい手順はSkillへ分ける、という考え方です。実際に読むファイルや適用範囲は製品ごとに異なるため、以下で個別に整理します。
Skills：必要な作業で読み込む手順と資料
Claude Code、Codex、GitHub Copilot、AntigravityのSkillsは、いずれも必要なときに作業手順をAIへ渡すための仕組みです。
Claude Codeの公式ドキュメントでは、SkillはSKILL.mdに指示を書き、作業に関連するときや、利用者が/skill-nameで呼び出したときにClaudeが使う仕組みとして説明されています。[1]
Codexでも、Skillは特定の作業に必要な能力を追加する仕組みです。最初にSkillの名前、説明、パスを把握し、必要になったときにSKILL.md全体を読みます。これはprogressive disclosure（必要な情報を段階的に読み込む方式）と呼ばれます。[2]
GitHub Copilotでは、Agent Skillsを、指示、スクリプト、リソースをまとめたフォルダとして扱います。公式ドキュメントでは、Copilot cloud agent、Copilot code review、GitHub Copilot CLI、GitHub Copilot app、VS CodeやJetBrains IDEのagent modeで使えると説明されています。agent modeは、AIが複数の操作を行いながら作業を進めるモードです。[3]
Googleは、Antigravityを「agentic development platform」、つまりAIエージェントが開発作業を進めるためのプラットフォームとして発表しています。[7] 公式サイトでは、Antigravity 2.0のカスタマイズとして、全体に適用するSkillsと、ワークスペース（作業用のプロジェクト領域）ごとのSkillsを定義できると説明しています。MCP（AIと外部ツールやデータを接続する仕組み）や、JSON Hooks（コマンド実行の前後など、決まったタイミングで自動処理を動かす仕組み）も定義できます。[8]
4つに共通するのは、Skillの説明を毎回すべてAIへ渡すのではなく、該当する作業で必要になったときに読み込むという点です。
初期指示ファイル：作業開始時に伝える前提
初期指示ファイルは、作業開始時にAIが読む前提で用意するファイルです。Skillのような個別の手順ではなく、プロジェクトの背景や、継続して適用したい方針を書きます。
Claude Codeでは、プロジェクト、ユーザー、組織の継続的な指示を書く場所としてCLAUDE.mdが説明されています。公式ドキュメントによると、Claudeはセッション開始時にこのMarkdownファイルを読みます。ビルドコマンド、コーディング規約、プロジェクト構造などを書く場所です。ビルドは、ソースコードから実行・公開できる成果物を作る処理を指します。[4]
Codexでは、AGENTS.mdがカスタム指示の起点です。Codexは、グローバルなCodexホーム（ユーザー共通の設定領域）と、プロジェクトルートから現在の作業ディレクトリまでの階層にあるAGENTS.mdやAGENTS.override.mdを読みます。下位ディレクトリの指示は、上位の指示の後ろに連結されます。[5]
GitHub Copilotでは、リポジトリ（プロジェクトのファイルをまとめて管理する場所）全体の指示に.github/copilot-instructions.mdを使えます。特定のパスに適用する指示には.github/instructions/NAME.instructions.md、AIエージェント向けの指示にはリポジトリ内のAGENTS.mdを使えます。GitHub Docsでは、対象ファイルに近いAGENTS.mdが優先されることも説明されています。[6]
Antigravityの公式Changelogには、GEMINI.mdに加え、AGENTS.mdからもルールを読む対応が追加されたと記載されています。[9] そのため、Antigravityの指示ファイルを整理する際は、両方をルールの読み込みに関係するファイルとして扱うのが安全です。
各ファイルの対象と適した内容
ファイル名だけで判断せず、どのツールが読むか、どの範囲へ適用するかを確認すると、指示の置き場所を決めやすくなります。
| ファイル | 主な対象 | 適した内容 |
|---|---|---|
| CLAUDE.md | Claude Code | 常に伝えたいプロジェクト方針、作業制約、コマンド |
| AGENTS.md | Codex、GitHub Copilotのエージェント機能など | リポジトリの方針、検証手順、ディレクトリ階層ごとのルール |
| GEMINI.md | Antigravity | Antigravity／Gemini系へ伝えたいプロジェクトのルール |
| .github/copilot-instructions.md | GitHub Copilot | リポジトリ全体の背景、ビルドやテストの方法 |
| .github/instructions/*.instructions.md | GitHub Copilot | 特定のパスやファイル種別に適用する指示 |
| SKILL.md／Skills | Claude Code、Codex、GitHub Copilot、Antigravityなど | 特定の作業の手順、チェックリスト、参考資料、スクリプト |
ファイル名にも注意が必要です。公式ドキュメントで多く使われている名前は、単数形のAGENT.mdではなく、複数形のAGENTS.mdです。リポジトリへ指示ファイルを置く際は、利用するツールが認識する正確な名前を確認します。
指示の置き場所を決める基準
読み込むタイミングと適用範囲を基に、プロジェクト全体で必要な前提と、作業ごとの手順を次のように分けられます。
| 書きたい内容 | 置き場所 |
|---|---|
| npm run buildの扱いに関するリポジトリの方針 | 初期指示ファイル |
| 日本語を先に書き、英語版を同じ構成で作るという方針 | 初期指示ファイル。必要に応じて共有ルールへまとめる |
| GitHub Actionsの失敗を調査する具体的な手順 | Skill |
| ブログ記事の構成、引用、文体を確認する手順 | Skill |
| 特定のフォルダだけで使う別の検証コマンド | 階層別のAGENTS.md、またはパス別のinstructions |
| 外部サービスやMCPを含む、再利用可能な機能の追加 | Plugin（拡張機能のパッケージ）やエージェント拡張 |
判断の中心は、その情報がすべての作業に必要か、特定の作業でだけ必要かです。前者は初期指示ファイル、後者はSkillに置きます。フォルダによって条件が変わる場合は、階層別・パス別の指示を使います。
Markdownの指示と操作制限の違い
CLAUDE.md、AGENTS.md、SKILL.mdは、AIエージェントが判断するときに参照する情報、つまりコンテキストです。「実行しないでください」と書いても、それだけで危険なコマンドの実行や秘密情報へのアクセスを必ず防げるわけではありません。
操作を制限したり、結果を検査したりする必要がある場合は、文書の指示に加えて、次のような実行側の仕組みを使います。
| 仕組み | 役割 |
|---|---|
| hooks | コマンド実行の前後などに自動処理を動かし、特定の操作を確認・ブロックする |
| sandbox | 権限や実行範囲を制限した環境で処理を動かす |
| approval policy | 操作前に人の承認を求める条件を定める |
| CI | GitHub Actionsなどで、テストや検証を自動実行する |
| 検証スクリプト | 定めた条件に沿って、ファイルや成果物を検査する |
Claude Codeの公式ドキュメントでも、CLAUDE.mdはコンテキストであり、操作を強制的に制限する設定ではないと説明されています。特定の操作をブロックするには、設定やhookなど、実行側の仕組みが必要です。[4]
CodexのAGENTS.mdも、作業前に読むカスタム指示です。実際の操作の制限は、承認ルール、sandbox、権限設定などで扱います。[5]
したがって、チームのルールでは、文書で何を指示するかと、設定で何を制限し、自動検査で何を確認するかを分けて説明する方が安全です。「このファイルが操作を禁止する」と書くだけでは、禁止の指示と、実際に操作を防ぐ仕組みの違いが伝わりません。
複数のAIで使う共通ルールの管理
Claude Code、Codex、GitHub Copilotを同じリポジトリで使う場合、それぞれの指示ファイルへ同じ長文をコピーすると、更新時に一部だけ修正され、内容がずれやすくなります。
このサイトでは、共通ルールをshared/へ置き、AGENTS.mdやClaude向けの初期指示ファイルには、作業開始時に必要な短い指示を残す構成にしています。この短い初期指示をbootstrap contractと呼び、最初に何を読み、どのルールを適用するかを定めています。
たとえば、コンテンツの引用ルール、ビルドの扱い、フォルダを安全に扱うためのルールはshared/rules/へ分け、各エージェントがそこから読む前提にしています。
| 管理する内容・対象 | 置き場所 |
|---|---|
| 共通ルール | shared/rules/ |
| Codexの初期指示 | AGENTS.md |
| Claude Codeの初期指示 | CLAUDE.md |
| Copilotの初期指示 | .github/copilot-instructions.mdやAGENTS.md |
| Antigravityの初期指示 | GEMINI.mdやAGENTS.md |
| 作業ごとの手順 | 各ツールが読めるSkill |
このように、共通ルールの基準となる保存先を1つ決めておけば、変更時に同じ内容を何か所も手で修正する負担を減らせます。各ツールの初期指示ファイルは共通ルールを読むための入口として使い、作業ごとの詳しい手順はSkillへ分けます。
ただし、ファイルの配置を決める前に、各製品が現在読むファイルと、その適用範囲・優先順位を公式仕様で確認する必要があります。
まとめ：全作業の前提と特定作業の手順を分ける
初期指示ファイルには、全作業で必要な短い前提や方針を書きます。Skillsには、特定の作業で必要になる手順や資料をまとめます。操作の制限や結果の検査は、hooks、sandbox、承認ルール、CI、検証スクリプトなどで行います。
複数のAIを使う場合は、共通ルールの保存先を決め、各ツールの初期指示ファイルから読む構成にすると、更新を管理しやすくなります。既存の指示も「全作業の前提」「特定作業の手順」「設定や自動検査で守る条件」に分けると、置き場所を判断しやすくなります。
参考文献
- Anthropic, Extend Claude with skills, Claude Code Docs
- OpenAI, Build skills, ChatGPT Learn
- GitHub Docs, About agent skills, GitHub Docs
- Anthropic, How Claude remembers your project, Claude Code Docs
- OpenAI, Custom instructions with AGENTS.md, ChatGPT Learn
- GitHub Docs, Adding repository custom instructions for GitHub Copilot, GitHub Docs
- Google Developers Blog, Build with Google Antigravity, our new agentic development platform, 2025年11月20日
- Google Antigravity, Antigravity 2.0, Google
- Google Antigravity, Changelog, Google
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。