copilot-instructions.md・*.instructions.md・AGENTS.md・SKILL.md、結局何が違うのか調べてみた

製造ビジネステクノロジー部の小林です。

GitHub Copilot CLI で package/infrastructure/ 配下の CDK ソースを修正する際のルールを設定しようとしたところ、設定方法がいくつかあって迷いました。

• copilot-instructions.md
• *.instructions.md
• AGENTS.md
• SKILL.md（Agent Skills）

結局何使えばいいんだっけ....となったので、それぞれの役割の違いを整理してみました。

各機能の役割

まず設計思想から整理します。

copilot-instructions.md

「リポジトリ全体に常に効くルール」

.github/copilot-instructions.md に配置するファイルで、リポジトリ内のあらゆる作業時に毎回コンテキストとして読み込まれます。コーディングスタイルや言語設定など、プロジェクト全体に共通するルールを書く場所です。

.github/
└── copilot-instructions.md    ← ★ リポジトリ全体に常に読み込まれる

https://docs.github.com/ja/copilot/how-tos/configure-custom-instructions/add-repository-instructions

*.instructions.md

「このファイルを触る時は、このルールで動いて」という静的なコーディングルール

.github/instructions/ 配下に配置し、applyTo に glob パターンを指定することで、対象ファイルを操作する際だけルールが読み込まれます。

.github/
└── instructions/
    └── cdk.instructions.md    ← ★ 特定パスにのみ読み込まれる

---
applyTo: "package/infrastructure/**"
---

# CDK コーディングルール

- スタックは機能単位で分割する
- パラメータは parameter.ts に記載する

AGENTS.md

「このディレクトリで作業する時は、こういう文脈を理解して動いて」というエージェント向けの作業指示書

対象ディレクトリに配置するだけで機能します。コーディングルールだけでなく、アーキテクチャの背景・注意事項・デプロイ手順なども含む、より広い「作業コンテキスト」を伝えるドキュメントです。

階層ごとに異なるコンテキストを定義できるのが最大の特徴です。作業ファイルに最も近い AGENTS.md が優先されるため、上位ディレクトリで共通ルール、下位ディレクトリで詳細ルールを定義できます。

infrastructure/
├── AGENTS.md                               ← プロジェクト全体のコンテキスト
├── cdk/
│   ├── AGENTS.md                           ← CDK 作業ならこの AGENTS.md が読まれる
│   ├── constructs
│   └── stack.ts
└── terraform/
    ├── AGENTS.md                           ← terraform 作業ならこの AGENTS.md が読まれる
    └── modules/

https://github.com/agentsmd/agents.md

SKILL.md（Agent Skills）

「このタスクが来たら、この専門知識を使って動いて」という AI への専門スキルの付与

.github/skills/ 配下に配置し、description に「どんな時に読むか」を記述します。ファイルやディレクトリではなくタスクの種類（会話の意図）に紐づくのが特徴で、「CDK のスタック設計をしてほしい」という会話を検知して自動ロードします。

.github/
├── skills/
│   └── cdk/
│       └── SKILL.md                        ← 会話の意図で自動ロード
└── copilot-instructions.md                 ← 必要に応じて全体ルール参照

---
name: cdk
description: AWS CDKスタック定義・リソース構成・デプロイ手順。
  Lambda/DynamoDB/EventBridgeのインフラ実装時に参照。
---

比較まとめ

結論

CDK のコーディングルールという用途には、*.instructions.md がよさそうです。

copilot-instructions.md → ルールが増えると肥大化しやすいですし、CDK が関係ない作業でも毎回読み込まれるのがちょっとノイズになりえます
AGENTS.md → コーディングルールだけじゃなく、アーキテクチャの背景・よくある地雷・デプロイ手順なども一緒に書きたい場合はこちらもアリです。ディレクトリ階層に沿って文脈を切り替えられるのも便利です
SKILL.md → ファイルやディレクトリじゃなく「タスクの種類（会話の意図）」で紐づけたい場合に向いています。「CDK スキル＋テストスキル」みたいに組み合わせて使えたり、他プロジェクトへ持ち出しやすかったりと、拡張性は一番高いです

まずは *.instructions.md + applyTo でシンプルに始めて、ルールが複数領域に広がってきたら SKILL.md への移行を検討するのがよさそうかなと思いました。

おわりに

似たようなファイルが複数あって最初は迷いましたが、「何をトリガーにするか」という観点で整理すると選びやすくなりました。公式ドキュメントにカスタマイズの早見表も整備されているので、ぜひ確認してみてください。

https://docs.github.com/ja/copilot/reference/customization-cheat-sheet

おまけ

いつでも思い出せるよう、それぞれの役割を一言でまとめました。

• copilot-instructions.md → リポジトリ全体に効く共通ルール
• *.instructions.md → 特定ファイルに効くコーディングルール
• AGENTS.md → 最寄りのディレクトリに置くエージェント向けの作業メモ
• SKILL.md → 特定タスクに応じてロードされる専門知識

それぞれのファイルの配置場所はこちらです。

.
├── .github/
│   ├── copilot-instructions.md          # リポジトリ全体に効く共通ルール
│   ├── instructions/
│   │   └── cdk.instructions.md          # 特定ファイルに効くコーディングルール
│   └── skills/
│       └── cdk/
│           └── SKILL.md                 # 特定タスクに応じてロードされる専門知識
└── package/
    └── infrastructure/
        └── AGENTS.md                    # エージェント向けの作業メモ