2026/02/26 時点の情報を自分なりに整理したメモです。
概要
本メモでは、Visual Studio Code 環境において GitHub Copilot が workspace 内の特定のパスにあるファイルを読み取り、プロジェクト固有のコンテキストやルールを自動的に適用する .github ディレクトリの仕様について、その詳細な構成、各設定ファイルが持つプロパティ、および具体的な活用例を網羅的に解説します。
前提条件
- Visual Studio Code がインストールされていること。
- GitHub Copilot 拡張機能がインストールされ、有効になっていること。
1. 機能概要と発動条件
.github フォルダ内の各設定ファイルは、そのカテゴリとパスに応じて、GitHub Copilot が特定の状況下で適用するルールやコンテキストを定義します。
| カテゴリ | ファイルパス | 主な役割 | 発動条件 |
|---|---|---|---|
| 全体指示 | copilot-instructions.md |
リポジトリ全体の基本ルール | 常時・自動 |
| 個別指示 | instructions/*.md |
特定のパスや言語にのみ適用 | 条件付き自動 (パス一致時) |
| プロンプト | prompts/*.prompt.md |
定型タスクの呼び出しコマンド |
手動 (/ コマンド) |
| エージェント | agents/*.md |
特定の専門家（ペルソナ）の定義 |
手動 (@ メンション) |
| スキル | skills/*/SKILL.md |
専門的な能力やツールのセット | 動的自動 (AI判断時) |
本メモで紹介する 「プレースホルダー構文（${selection} や ${input} 等）」は, 現時点で Visual Studio Code / GitHub Copilot における独自の連携仕様です。Cursor, Windsurf, Trae といった他社エディタでは, 同様の機能を @メンション や独自のルールファイル（.cursorrules 等）で実現しており, ${...} 構文をそのまま利用することはできません。
動作フローの視覚化
ユーザーの入力（トリガー）の種類によって、どの設定ファイルが読み込まれるかの分岐は以下のようになります。
2. ディレクトリ構造の視覚化
.github フォルダの標準的なディレクトリ構造は以下の通りです。
.github/
├── copilot-instructions.md # プロジェクト全体の「共通の掟」
├── instructions/ # 【自動】条件付きで適用
│ └── backend.instructions.md
├── prompts/ # 【手動】スラッシュコマンド（メニュー）
│ └── check.prompt.md # → /check で呼び出し
├── agents/ # 【手動】特定エージェント（担当者）
│ └── security-expert.md # → @security-expert の定義
└── skills/ # 【動的】専門スキル（Agent Skills）
└── cloud-deploy/
├── SKILL.md # スキル定義（自動起動トリガー）
└── scripts/ # 実行スクリプト・外部ツール
3. 各ファイルの詳細仕様と全プロパティ
凡例
- [必須]: ファイルが動作するために必ず記述が必要な項目。
- [Pre-release]（先行導入）: 正式採用がほぼ確定しており, 最新版やプレビュー版で利用可能な最新仕様。
- [Experimental]（実験的）: 開発初期段階の機能。仕様変更の可能性が高く, 特定の環境でのみ動作する試作仕様。
3.1. 全体指示 (copilot-instructions.md)
リポジトリ全体に適用される「常に有効なコンテキスト」を定義します。このファイルにはYAMLヘッダーは不要であり、記述された内容がそのままCopilotの全体的な振る舞いや回答に影響を与えます。
3.2. 個別指示 (instructions/*.instructions.md)
特定のディレクトリやファイル形式に一致する場合のみ適用されるルールです。ファイル名には .instructions.md のサフィックスを付与します。
プロパティ一覧
| プロパティ名 | 区分 | 意味・役割 |
|---|---|---|
applyTo |
[必須] | 指示を適用するファイルパス（globパターン）。複数のパターンを指定することも可能です。 |
name |
任意 | UI上で表示される指示の名称。Copilotのインターフェースでこのルールが適用されていることを示す際に使用されます。 |
excludeAgent |
任意 | 特定のエージェント（例: code-review）をこの指示の対象から除外します。これにより、エージェントごとに異なるルールを適用できます。 |
priority |
任意 | 指示が重複した場合の優先度を指定する数値。数値が高いほど優先されます。 |
applyTo を使ったYAML記述例
例1：TypeScriptのAPI開発ルール
src/api/ 配下の TypeScript ファイルにのみ、特定の型定義ライブラリ（zod）の使用を強制する場合の記述例です。
---
applyTo: "src/api/**/*.ts"
name: "API Type-Safety Rules"
---
このディレクトリでは、APIの入出力の型定義に `zod` を使用してください。
他のバリデーションライブラリ（Joi, Yupなど）は使用しないでください。
例2：Javaのテストコード規約
src/test/java/ 配下の Java ファイルに対して、JUnit 5 を使ったテストの書き方を指示する場合の記述例です。
---
applyTo: "src/test/java/**/*.java"
name: "JUnit 5 Test Convention"
---
テストクラス名は `*Test.java` または `*Tests.java` で終えるようにしてください。
アサーションには `org.junit.jupiter.api.Assertions` を使用します。
3.3. カスタムプロンプト (prompts/*.prompt.md)
ユーザーが /コマンド で呼び出す、再利用可能な定型タスクのテンプレートです。ファイル名には .prompt.md のサフィックスを付与します。
プロパティ一覧
| プロパティ名 | 区分 | 意味・役割 |
|---|---|---|
description |
任意 | コマンド選択時に表示される説明文。ユーザーがスラッシュコマンドを入力した際に、この説明が表示され、適切なコマンドを選択する手助けとなります。 |
agent |
任意 | このプロンプトを処理する担当エージェントの指定。特定のエージェント（例: @security-expert）にタスクを委譲する場合に設定します。 |
model |
任意 | プロンプト処理に使用するAIモデルの指定。特定のモデル（例: gpt-4o）に固定したい場合に設定します。 |
mode |
任意 | 動作モードを指定します。chat は会話形式での応答、insert はエディタへの直接挿入を示します。 |
context |
任意 | プロンプト実行時に自動的に参照するファイルを指定します。動的な変数（${current_file}など）も利用可能です。 |
variables |
[Experimental] | ユーザーに入力を促す変数を定義します。これにより、プロンプトの柔軟性が向上します。 |
3.4. カスタムエージェント (agents/*.md)
@ で呼び出す、特定の専門知識を持たせたペルソナを定義します。
プロパティ一覧
| プロパティ名 | 区分 | 意味・役割 |
|---|---|---|
name |
[必須] | エージェントの識別名。@名称 で呼び出す際に使用される名前です。 |
description |
[必須] | エージェントの役割に関する説明。Copilotがこのエージェントをどのように活用すべきかを判断する際の重要な情報となります。 |
model |
任意 | 使用するAIモデルの指定。このエージェントに特定のモデルを使用させたい場合に設定します。 |
tools |
任意 | エージェントに許可するツールリスト。エージェントが実行できるアクション（例: read、search、run_shell_command）を制限します。 |
mcp-servers |
[Pre-release] | 接続するMCPサーバーのリスト。複数のサーバーと連携する場合に利用されます。 |
capabilities |
[Pre-release] | 特殊機能（例: code-interpreter）の有効化。エージェントにコードの実行や解釈能力を付与します。 |
3.5. エージェントスキル (skills/*/SKILL.md)
AI が必要だと判断した時に自動ロードされる専門知識・ツール群です。各スキルは専用のサブディレクトリ内に SKILL.md というファイル名で定義されます。
プロパティ一覧
| プロパティ名 | 区分 | 意味・役割 |
|---|---|---|
name |
[必須] | スキルの一意な名称。このスキルを識別するために使用されます。 |
description |
[必須] | AIがスキル起動を判断するためのトリガーとなる説明文。AIがユーザーの意図と合致すると判断した場合にスキルが自動的にロードされます。 |
metadata |
任意 | バージョン、作者、連絡先などの任意のメタデータを記述します。 |
allowed-tools |
[Experimental] | スキルに許可するツールのホワイトリスト。スキルが実行できる外部ツールや内部機能を制限します。 |
4. 実践的な使用例：エージェント定義とプロンプトの連携
ここでは、カスタムエージェントとカスタムプロンプトを組み合わせて特定のタスクを実行する例を示します。
手順1：担当エージェントの定義 (agents/security-expert.md)
セキュリティ監査を専門とするエージェントを定義します。
---
name: security-expert
description: セキュリティ脆弱性の監査を専門とするエージェント
model: gpt-4o
tools: ["read", "search"]
---
あなたは世界最高峰のセキュリティエンジニアです。
OWASP基準に基づき, コードの脆弱性を正確に指摘してください。
このエージェントは security-expert という名前で @security-expert として呼び出され、GPT-4oモデルを使用し、ファイルの読み込み (read) と検索 (search) ツールのみを実行できます。役割としてOWASP基準に基づくコードの脆弱性指摘が設定されています。
手順2：仕事の注文票の作成 (prompts/check.prompt.md)
上記で定義したエージェントを活用するプロンプトを作成します。
---
description: 選択したコードのセキュリティスキャンを実行します
agent: security-expert
---
以下のコードに対して, セキュリティチェックを行ってください。
追加の指示: ${input}
このプロンプトは /check コマンドで呼び出され、「選択したコードのセキュリティスキャンを実行します」という説明が表示されます。agent: security-expert が指定されているため、このプロンプトの処理は security-expert エージェントに委譲されます。また、${input} 変数を使用することで、ユーザーがコマンドの後に追加入力した指示をプロンプトに組み込むことができます。
5. 変数（プレースホルダー）による動的指示
プロンプトファイルのボディ部分では、以下の変数を使用して、現在のコンテキストに基づいた動的な指示を組み立てることができます。
| 変数名 | 取得される内容 |
|---|---|
${input} |
ユーザーがスラッシュコマンドの後に手動入力したテキスト。例えば /refactor "可読性向上" の "可読性向上" の部分。 |
${selection} |
エディタ上で現在選択されているコード範囲。これにより、特定のコードブロックに対して操作を指示できます。 |
${current_file} |
現在開いているアクティブなファイルの内容全体。ファイル全体の分析や要約に利用されます。 |
${git_diff} |
Gitのステージングされている変更差分。コードレビューやコミットメッセージの生成などに活用できます。 |
【自作コマンド】の実用的組み合わせ例
以下の例は、.github/prompts/ 配下に該当するファイル名（例: refactor.prompt.md）を作成した場合に有効になります。
例1：選択範囲のリファクタリング (/refactor [指示])
以下のコードをリファクタリングしてください。
コード：
${selection}
リファクタリングの方針：
${input}
このプロンプトは、ユーザーがエディタで選択したコード (${selection}) に対して、コマンドの後に入力した指示 (${input}) に基づくリファクタリングをCopilotに依頼します。
例2：ファイル全体の目的確認 (/explain-file [質問])
このファイルの内容を要約し, 私の質問に答えてください。
ファイル内容：
${current_file}
私の質問：
${input}
このプロンプトは、現在開いているファイル全体 (${current_file}) の内容をCopilotに渡し、ユーザーが入力した質問 (${input}) に回答するよう指示します。
6. トラブルシューティングと運用上の注意点
効率的かつ安全に .github 設定ファイルを運用するために、以下の点に注意してください。
-
公開設定と機密情報:
これらの設定ファイル（.githubフォルダ内のファイル）はリポジトリにコミットされるため、公開リポジトリの場合は世界中に公開されます。 API キーや認証情報、個人を特定できる情報などの機密情報は絶対に直接記述せず、環境変数やシークレット管理ツール（例: GitHub Secrets）を併用してください。 -
コンテキスト・ウィンドウの節約:
copilot-instructions.md（全体指示）に過剰な情報を詰め込みすぎると、AIの記憶容量（コンテキスト・ウィンドウ）を無駄に消費し、その結果、本来の質問への回答精度が低下する可能性があります。特定の技術トピックや言語ごとのルールはinstructions/やskills/ディレクトリに分散させ、「必要な時だけ読み込ませる」 設計を推奨します。 -
スキルの誤作動（衝突）防止:
エージェントスキルのdescriptionが曖昧だと、AIがどのスキルを使うべきかを正確に判断できず、意図しないスキルが発動したり、あるいはどのスキルも発動しなかったりする可能性があります。「このスキルは何ができるか」「どのような状況で役立つか」を具体的に記述することで、AIによる自動起動の精度を最大化できます。