AI AgentのSkillsと指示ファイルの使い分け
この記事で学べること
- Skillsと初期指示ファイルを読み込みタイミングと役割で分ける考え方
- CLAUDE.md、AGENTS.mdなどのファイルへ何を書くかを決める基準
- Markdown指示の限界を踏まえ、複数AIで共通ルールを管理する設計
Skillsと指示ファイルを読み込むタイミングで分ける
常に必要な前提は初期指示ファイルへ置き、特定作業だけで使う手順はSkillへ分けます。このサイトでClaude CodeとCodexを併用した結果、同じ指示を複製するより、読み込む時点と対象範囲をそろえるほうが運用しやすいと分かりました。安全上の強制が必要な規則は、どちらの文書にも任せず、権限設定や自動検査へつなぎます。
この記事では、「常時読む指示と必要時だけ読むSkillへ、どの情報を分けるか」という問いに焦点を当て、選択を分ける比較軸、向いている条件、選択後の確認事項を扱います。
最後まで読むと、「常時読む指示と必要時だけ読むSkillへ、どの情報を分けるか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
Skillsは必要時、初期指示ファイルは作業開始時に読み込む
大きく分けると、次の2種類です。
| 種類 | 役割 | 例 |
|---|---|---|
| 常時読む指示ファイル | プロジェクトの前提、方針、注意事項、検証コマンドを最初から伝える | CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md |
| Skills | 必要なタスクにだけ読み込む作業手順、専門ワークフロー、参考資料、スクリプト | SKILL.md |
つまり、常に守ってほしい短いルールは初期指示ファイルに置き、必要なときだけ使う長めの手順はSkillに分ける、という考え方です。
Skillsは必要なときに使う作業手順
Claude Code Skills、Codex Skills、GitHub Copilot Skills、Antigravity Skillsはいずれも、必要なときにタスク手順を渡すための仕組みです。Claude Codeの公式ドキュメントでは、Skillは SKILL.md に指示を書き、関連するときや /skill-name で呼び出したときにClaudeが使う仕組みとして説明されています。[1]
Codexでも、Skillはタスク固有の能力を追加するための仕組みです。Codexは最初に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で使えると説明されています。[3]
Google Antigravityは、Googleの公式発表で「agentic development platform」と説明されています。公式サイトでは、Antigravity 2.0のカスタマイズとして、グローバルまたはワークスペース固有のSkills、MCP、JSON Hooks（コマンド実行の前後など決まったタイミングで自動処理を動かす仕組み）を定義できると説明されています。[7][8]
4つに共通するのは、Skillが「毎回コンテキストに全部入れる説明」ではなく、「該当するタスクで必要になったときに読む説明」だという点です。
初期指示ファイルは作業前に読む前提
初期指示ファイルは、Skillとは逆に、作業開始時に読まれる前提のファイルです。
Claude Codeでは、プロジェクトやユーザー、組織の継続的な指示を書く場所として CLAUDE.md が説明されています。公式ドキュメントでは、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 agent向けの指示としてリポジトリ内の AGENTS.md を使えます。GitHub Docsでは、agent instructionsとして AGENTS.md をリポジトリ内に置けること、近い AGENTS.md が優先されることも説明されています。[6]
Antigravityでは、公式Changelogで GEMINI.md に加えて AGENTS.md からrulesを読む対応が追加されたことが説明されています。[9] そのため、Antigravityを比較に入れる場合は、GEMINI.md と AGENTS.md の両方を「ルール読み込みに関係するファイル」として扱うのが安全です。
指示ファイルは対象ツール、SKILL.mdは作業手順を定義する
| ファイル | 主な対象 | 向いている内容 |
|---|---|---|
CLAUDE.md | Claude Code | Claude Codeに常に伝えたいプロジェクト方針、作業制約、コマンド |
AGENTS.md | Codex、GitHub Copilot agent系 | AI agentに常に伝えたいリポジトリ方針、検証手順、階層別ルール |
GEMINI.md | Antigravity | Antigravity/Gemini系に伝えたいプロジェクトrules |
.github/copilot-instructions.md | GitHub Copilot | Copilotにリポジトリ全体の背景やビルド・テスト方法を伝える指示 |
.github/instructions/*.instructions.md | GitHub Copilot | 特定のパスやファイル種別にだけ適用したい指示 |
SKILL.md / Skills | Claude Code、Codex、GitHub Copilot、Antigravityなど | 特定タスクの手順、チェックリスト、参考資料、スクリプト |
注意したいのは、AGENT.md ではなく、公式に多く出てくる名前は AGENTS.md だという点です。リポジトリの指示ファイルを作るときは、単数形ではなく複数形のファイル名を確認する必要があります。
常時必要な前提は指示ファイル、特定作業の手順はSkillsへ書く
私は、次のように分けるのが実務では扱いやすいと考えています。
| 書きたい内容 | 置き場所 |
|---|---|
npm run build の扱いに関するリポジトリ方針 | 初期指示ファイル |
| 日本語を先に書き、英語版を同じ構成で作る | 初期指示ファイル、必要なら共有ルール |
| GitHub Actionsの失敗を調査する具体的な手順 | Skill |
| ブログ記事を作るときの構成、引用、文体チェック | Skill |
| 特定フォルダだけ別の検証コマンドを使う | 階層別の AGENTS.md またはパス別instructions |
| 外部サービスやMCPを含めた再利用可能な拡張 | Pluginやエージェント拡張 |
短く言うと、プロジェクト全体の前提は初期指示ファイル、作業単位の手順はSkillです。
Markdown指示は強制境界ではない
CLAUDE.md、AGENTS.md、SKILL.md は、エージェントの行動を促すためのコンテキストです。これらを書くだけで、危険なコマンドの実行や秘密情報へのアクセスを必ず防げるわけではありません。必要に応じて、hooks、sandbox（権限や実行範囲を制限する隔離された実行環境）、approval policy（AIやツールが操作する前に人の承認を求めるための許可ルール）、CI（GitHub Actionsなどでテストや検証を自動実行する仕組み）、検証スクリプトなどの実行側の仕組みと組み合わせます。
Claude Codeの公式ドキュメントでも、CLAUDE.md はコンテキストであり、強制設定ではないと説明されています。特定の操作をブロックしたい場合は、設定やhookなどの実行側の仕組みを使う必要があります。[4]
Codexも、AGENTS.md は作業前に読むカスタム指示ですが、実行制御そのものはapproval、sandbox、権限設定などの層で扱います。[5]
そのため、記事やチームルールで「このファイルが禁止する」と書くよりも、「このファイルで指示し、必要に応じてhooks、sandbox、CI、review scriptで確認する」と分けて考える方が安全です。
複数エージェントで使う場合の設計
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
同じ内容を複数箇所に手で貼るより、一次情報源を決めておく方が、後からルールを変えるときに管理しやすくなります。
まとめ：Skillsと指示ファイルは読み込み時点と強制方法で分ける
Skillsと初期指示ファイルは、どちらもAIに文脈を渡す仕組みですが、使う場面が違います。
CLAUDE.md、AGENTS.md、GEMINI.md、.github/copilot-instructions.mdは、作業開始時から渡したい短い前提を書く場所SKILL.mdは、必要なときだけ読み込む専門手順を書く場所- Claude Codeは
CLAUDE.md、CodexはAGENTS.md、GitHub Copilotは.github/copilot-instructions.mdとAGENTS.md、AntigravityはGEMINI.mdとAGENTS.mdをそれぞれ扱う - Markdown指示だけで安全性を強制するのではなく、hooks、sandbox、approval、CI、review scriptと組み合わせて考える
複数のAIエージェントを使うほど、指示ファイルは増えます。増やすこと自体が問題なのではなく、常時読むルール、必要時に読むSkill、機械的に検証する仕組みを分けておくことが重要です。
最初の行動は、既存の指示を「全作業で必要」「特定作業だけで必要」「機械的に強制する」の3列へ振り分けることです。各製品が読むファイルや優先順位は変わる可能性があるため、実際の配置前に現在の公式仕様を確認します。
参考文献
- 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
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。