GitHub Copilot Agent Skills ガイド【2026年最新】SKILL.mdの書き方から実践活用まで¶
対象 / ポイント
対象: エージェントに手順知識を渡して自律実行させたい開発チーム
ポイント:
- SKILL.mdに手順・スクリプト・テンプレートを書くと、Copilot / Claude Code / Codex / Cursor等の複数ツールで再利用しやすいスキルパッケージになる
- Progressive Disclosureにより、必要なスキルだけをオンデマンドで読み込む設計になる
- Custom Instructions（常時適用）との使い分けが明確になり、コンテキスト効率が上がる
⚡ 5分で始めるクイックスタート
# 1. スキルディレクトリを作成
mkdir -p .github/skills/webapp-testing
# 2. SKILL.mdを作成
cat << 'EOF' > .github/skills/webapp-testing/SKILL.md
---
name: webapp-testing
description: >-
Webアプリのテスト自動化を支援する。
テスト、test、E2E、単体テストの話題で使用する。
---
## Procedure
1. テスト対象を分析
2. AAAパターンでテスト作成
3. 実行して結果を検証
EOF
# 3. settings.jsonでスキルパスを設定
# .vscode/settings.json に追加:
# { "chat.agentSkillsLocations": { ".github/skills/**": true } }
# 4. コミット
git add .github/skills/
git commit -m "Add webapp-testing skill"
検証: VS Code Copilot Chatで /skills と入力 → webapp-testing が一覧に表示されれば成功
📖 Agent Skills とは¶
Agent Skillsは、AIコーディングエージェントに専門的な手順知識を与えるための仕組みです。GitHub Copilotのエコシステムでは、SKILL.mdファイルに記述された手順・スクリプト・テンプレートを、エージェントが必要に応じて参照し、タスクの精度を向上させます。
オープン標準としてのAgent Skills
Agent Skillsはagentskills.ioでAnthropicが策定したオープンフォーマットです。GitHub Copilotでは、Copilot cloud agent、GitHub Copilot CLI、VS Code の agent mode が Agent Skills に対応しています。GitHub Docsでは、プロジェクトスキルの配置先として .github/skills、.claude/skills、.agents/skills が案内されています。仕様の全体像は Agent Skills 完全ガイド（初級編） を参照してください。
Copilotにおけるスキルの位置づけ¶
Copilotのコンテキストシステムは以下の3層で構成されています。
スキルは手順の標準パッケージ
スキルは「再利用可能な手順知識パッケージ」と捉えるのが最も分かりやすいでしょう。単なるテキスト指示ではなく、スクリプト・テンプレート・参照ドキュメントなどの資産を含む一式のフォルダです。
⚙️ VS Codeでの有効化と配置¶
settings.json での設定¶
VS Codeでスキルを有効にするには、settings.jsonに読み込みパスを設定します。
{
"chat.agentSkillsLocations": {
".github/skills/**": true,
".agents/skills/**": true
}
}
設定の確認方法
VS Code のチャットパネルで /skills と入力すると、Configure Skills メニューが開きます。ここから現在読み込まれているスキルの一覧確認、有効化/無効化の切り替えが可能です。
スキルファイルの配置場所¶
プロジェクトスキル（リポジトリ内）¶
project-root/
├── .github/
│ └── skills/
│ ├── webapp-testing/
│ │ └── SKILL.md # テスト自動化スキル
│ ├── doc-generator/
│ │ └── SKILL.md # ドキュメント生成スキル
│ └── release-workflow/
│ ├── SKILL.md # リリース手順スキル
│ └── checklist.md # 参照リソース
├── .claude/skills/ # Claude Code互換
└── .agents/skills/ # 汎用エージェント互換
推奨配置: .github/skills/
GitHub Copilotを主に使用する場合は .github/skills/ への配置を推奨します。GitHub Docsでは、プロジェクトスキルとして .github/skills、.claude/skills、.agents/skills がサポート対象です。他のエージェントツールとの互換性を重視する場合は .agents/skills/ も検討してください。
パーソナルスキル（ユーザーローカル）¶
個人の作業環境にのみ適用するスキルは、ホームディレクトリに配置します。
~/.copilot/skills/ # Copilot専用
~/.agents/skills/ # 汎用エージェント互換
パーソナルスキルはリポジトリにコミットされないため、個人の好みや環境固有の手順を定義するのに適しています。
Organization / Enterprise レベルのスキル
組織・エンタープライズレベルでのスキル共有機能は Coming Soon として発表されています。現時点ではリポジトリ内配置またはパーソナルスキルで運用してください。
🏗️ SKILL.md のフォーマット¶
SKILL.mdはYAMLフロントマター + Markdown本文の構成です。
フロントマター（メタデータ）¶
---
# ── agentskills.io 標準フィールド ──
name: webapp-testing # 必須: 小文字+ハイフン、最大64文字
description: >- # 必須: 最大1024文字
Webアプリのテスト戦略と自動テスト作成を支援する。
テスト、test、E2Eの話題で使用する。
license: MIT # 任意: ライセンス名またはファイル参照
metadata: # 任意: 任意のkey-valueマッピング
author: dev-team
version: "1.0"
compatibility: >- # 任意: 環境要件（最大500文字）
Requires Node.js 18+, network access for npm install
# allowed-tools: Bash Edit ... # Experimental: スキルが使えるツールを制限
# ── Copilot 固有の拡張フィールド ──
argument-hint: "テスト対象のファイルパスまたはモジュール名" # VS Code向け引数ヒント
user-invokable: true # ユーザーが手動起動可能か（デフォルト: true）
disable-model-invocation: false # モデルの自動起動を無効化（デフォルト: false）
---
各フィールドの詳細¶
| フィールド | 必須 | 出典 | 説明 |
|---|---|---|---|
name | Yes | 標準 | スキルの一意識別子。小文字・ハイフン区切り、最大64文字 |
description | Yes | 標準 | スキルの説明。最大1024文字。発動条件のキーワードを含めることが重要 |
license | No | 標準 | スキルのライセンス名（MIT, Apache-2.0等）またはファイル参照 |
metadata | No | 標準 | 任意のkey-valueマッピング。author, version等の補足情報 |
compatibility | No | 標準 | 環境要件の記述（最大500文字）。必要なランタイムやネットワークアクセス等 |
allowed-tools | No | 標準 | スキルが使用できるツールを制限（Experimental） |
argument-hint | No | Copilot固有 | ユーザーがスキルを呼び出す際の引数ヒント（VS Code向け） |
user-invokable | No | Copilot固有 | true（デフォルト）でユーザーが手動起動可能 |
disable-model-invocation | No | Copilot固有 | trueにするとモデルの自動判断による起動を無効化 |
標準 vs Copilot固有
「標準」は agentskills.io/specification で定義されたフィールドで、Claude Code・Codex等でも共通で利用できます。「Copilot固有」はVS Code / GitHub Copilotのみで解釈される拡張フィールドです。
発火キーワードが品質の8割
descriptionの書き方が発動精度を左右する
description にはスキルが対応する話題やキーワードを明示的に含めてください。Copilotは description を読んでスキルの発動判断を行うため、曖昧な説明では適切に発動しません。具体的なキーワード設計のガイドは description設計ガイド を参照してください。
本文（Markdown）¶
フロントマター以降は通常のMarkdownで、手順・ルール・出力例などを記述します。
## Goal
テストカバレッジを向上させ、品質を標準化する。
## Procedure
1. 対象コードを分析し、テスト戦略を決定
2. テストファイルを作成
3. テストを実行して結果を検証
## References
- [テストテンプレート](./test-template.js)
- [命名規則ドキュメント](./naming-conventions.md)
ファイル参照は相対パスで
SKILL.md内から他のファイルを参照する場合は、SKILL.mdからの相対パスで記述します。Copilotはこれらのファイルをリソースとして読み込み、コンテキストに含めます。
🔄 Progressive Disclosure（段階的ローディング）¶
Agent Skillsの最大の特長はProgressive Disclosure（段階的ローディング）です。この仕組みにより、多数のスキルをインストールしてもコンテキストウィンドウを圧迫しません。
3段階のローディングプロセス¶
上部ダイアグラムの「Progressive Disclosure」セクションで、L1（発見）→ L2（指示読み込み）→ L3（リソース展開）の3段階を図示しています。
なぜ重要か¶
上部ダイアグラムの「従来のアプローチ vs Agent Skills」比較を参照してください。
スキル数の目安
1プロジェクトに10〜30のスキルを登録しても、実際にコンテキストに展開されるのは1〜3つ程度です。スキルを細かく分割して、専門性の高い手順パッケージとして管理するのが効果的です。
📊 Copilot エコシステムでの対応状況¶
2026年2月時点でのAgent Skills対応状況は、上部の「SKILL.md構造」ダイアグラム下段で図示しています。
Copilot Coding Agent でのスキル活用
Copilot Coding Agentは、Issueからの自律実行時に .github/skills/ 配下のスキルを自動的に参照します。たとえば「テストを追加して」というIssueに対して、webapp-testing スキルの手順に従ってテストコードを生成し、PRを作成します。
Before / After: Skills有/無のエージェント出力比較¶
プロンプト: 「テストを追加して」
→ エージェントが汎用的なテストを生成
→ 命名規則バラバラ、AAAパターン不統一
→ 手動で修正が必要
プロンプト: 「テストを追加して」
→ webapp-testing スキルが自動発動
→ AAA パターン、命名規則統一、カバレッジ方針準拠
→ そのままPRに出せる品質
🎯 Custom Instructions との使い分け¶
Agent SkillsとCustom Instructions（カスタムインストラクション）は目的が異なります。適切に使い分けることで、コンテキストの効率化と指示の精度を両立できます。
| 観点 | Agent Skills | Custom Instructions（.instructions.md） | copilot-instructions.md |
|---|---|---|---|
| 目的 | 専門的なワークフロー・手順 | パス別のコーディング規約 | プロジェクト全体の基本ルール |
| 読み込み | オンデマンド（必要時のみ） | パターンマッチ（applyTo） | 常時適用 |
| 内容 | 手順+スクリプト+例+参照 | インストラクションのみ | インストラクションのみ |
| 可搬性 | オープン標準（全ツール共通） | VS Code固有 | GitHub固有 |
| 標準 | agentskills.io | VS Code specific | GitHub specific |
| 適用粒度 | タスク・話題単位 | ファイルパス単位 | リポジトリ全体 |
判断フローチャート¶
AGENTS.md によるクロスツール統一管理
AGENTS.mdファイルを使うと、GitHub Copilot・Claude Code・OpenAI Codex等の複数エージェントに対する共通指示を1つのファイルで管理できます。詳しくは マルチエージェント協働ガイド を参照してください。
copilot-instructions.mdと.instructions.mdの書き方・設計パターン
ファイルパス別の条件分岐型インストラクション管理
💡 実践例：テスト自動化スキル¶
以下は、Webアプリケーションのテスト自動化を支援するスキルの完全な例です。
ディレクトリ構成¶
.github/skills/webapp-testing/
├── SKILL.md # スキル本体
├── test-template.js # テストテンプレート
└── naming-conventions.md # 命名規則リファレンス
SKILL.md¶
---
name: webapp-testing
description: >-
Webアプリケーションのテスト戦略と自動テスト作成を支援する。
テスト、test、E2E、単体テスト、integration testの話題で使用する。
license: MIT
metadata:
author: dev-team
version: "1.0"
---
## Goal
テストカバレッジを向上させ、テスト品質を標準化する。
## Testing Strategy
1. **単体テスト**: ビジネスロジックの境界値を優先
2. **統合テスト**: API endpoint + DB の結合確認
3. **E2Eテスト**: ユーザーフロー（ログイン→操作→結果確認）
## Naming Convention
- テストファイル: `*.test.ts` or `*.spec.ts`
- テスト名: `describe('機能名') > it('期待する動作')` 形式
## Output Format
- テスト実行前にスキーマ検証を追加
- AAA (Arrange-Act-Assert) パターンで構造化
- 各テストにコメントで意図を明記
## References
- [テストテンプレート](./test-template.js)
- [命名規則](./naming-conventions.md)
descriptionにキーワードを列挙する
description に「テスト、test、E2E、単体テスト、integration test」のように関連キーワードを含めることで、ユーザーがこれらの話題に触れた際にスキルが自動発動します。
実践例：ドキュメント生成スキル
APIドキュメントやREADMEの自動生成を支援するスキルの例です。テスト自動化スキルとは異なり、出力ルールに重点を置いた構成になっています。
.github/skills/doc-generator/
├── SKILL.md # スキル本体
├── readme-template.md # READMEテンプレート
└── changelog-format.md # CHANGELOG形式リファレンス
---
name: doc-generator
description: >-
APIドキュメントやREADME、CHANGELOG の生成・更新を支援する。
ドキュメント、documentation、README、API doc、CHANGELOGの話題で使用する。
metadata:
author: dev-team
version: "1.0"
---
## Procedure
1. 対象コードを読み取り、公開APIを特定
2. JSDoc/docstring形式のコメントを追加
3. README.mdの該当セクションを更新
4. CHANGELOGに変更内容を追記（Keep a Changelog形式）
## Output Rules
- コードブロックには必ず言語指定を付与
- APIエンドポイントはメソッド・パス・パラメータ・レスポンス例を記載
- 破壊的変更には ⚠️ マークを付与
## References
- [READMEテンプレート](./readme-template.md)
- [CHANGELOG形式](./changelog-format.md)
🛠️ スキル作成のベストプラクティス¶
1. スキルの粒度設計¶
1スキル = 1専門領域
スキルは単一の専門領域にフォーカスしてください。「テスト+デプロイ+ドキュメント」を1つのスキルにまとめると、不要な場面でもコンテキストを消費します。
# ❌ 非推奨: 範囲が広すぎるスキル
name: everything-helper
description: テスト、デプロイ、ドキュメント、コードレビューを全部やる
# ✅ 推奨: 専門領域を絞ったスキル
name: webapp-testing
description: Webアプリのテスト戦略と自動テスト作成を支援する
2. descriptionの設計原則¶
| 原則 | 例 |
|---|---|
| 具体的なキーワードを含める | 「テスト、test、E2E、単体テスト」 |
| 対象範囲を明示する | 「Webアプリケーションの」 |
| 動作を動詞で記述する | 「支援する」「生成する」「検証する」 |
| 1024文字以内に収める | 簡潔かつ網羅的に |
descriptionの設計をさらに深掘りしたい場合は description設計ガイド（スキル発動精度を高める具体的なパターン集）を参照してください。
3. 参照リソースの活用¶
SKILL.md本文は手順の概要に留め、詳細なテンプレートやスクリプトは別ファイルに分離します。これにより、Level 3（Resources）でのみ読み込まれるため、コンテキスト効率が向上します。
.github/skills/my-skill/
├── SKILL.md # 手順概要（Level 2で読み込み）
├── templates/
│ ├── component.tsx # コンポーネントテンプレート（Level 3）
│ └── test.spec.ts # テストテンプレート（Level 3）
└── examples/
└── sample-output.md # 出力例（Level 3）
❓ よくある質問 (FAQ)¶
Q: スキルが発動しない場合はどうする？
/skillsコマンドでスキルが有効化されているか確認settings.jsonのchat.agentSkillsLocationsパスが正しいか確認descriptionに適切なキーワードが含まれているか見直すdisable-model-invocation: trueになっていないか確認
Q: スキルの数に上限はある？
公式に上限は明示されていませんが、実用上の注意点はあります。Level 1（Discovery）メタデータは軽量ですが、Copilot CLIでは49スキルを登録した際に31スキルしか表示されなかった事例が報告されています（Issue #1130）。これはCLI固有の挙動とみられますが、スキル数が増えるとコンテキスト制限に当たる可能性があるため、実際に使うスキルに絞って管理することを推奨します。
Q: Claude Codeで作ったスキルをCopilotでも使える？
はい。Agent SkillsはagentSkills.ioのオープンフォーマットに準拠しているため、.claude/skills/ に作成したSKILL.mdを .github/skills/ にコピー（またはシンボリックリンク）するだけで利用できます。フォーマットは共通です。
🔗 関連記事¶
Copilot シリーズ¶
copilot-instructions.mdと.instructions.mdの書き方・設計パターン
ファイルパス別の条件分岐型インストラクション管理
複数AIツールで共通利用できるプロジェクト命令ファイル
GitHub CopilotとClaude Codeの使い分け戦略
参考資料（Agent Skills 深掘り）¶
- Agent Skills 完全ガイド（初級編） — オープンフォーマットとしてのAgent Skillsの基礎知識
- Agent Skills 導入ガイド — すぐ使える具体例10選とインストール方法
- description設計ガイド — スキル発動精度を高めるdescriptionの書き方
- Skills の陳腐化と運用設計 — 作ったSkillの評価ループ・保守設計