.github-private のカスタムエージェントが参照する Agent Skills

1. はじめに：よくある誤解

GitHub Organization に .github-private リポジトリを作って agents/ 配下にカスタムエージェントを置けば、組織のメンバー全員がそのエージェントを利用できる——ここまでは GitHub 公式ドキュメント に記載のある正しい挙動です。

ここで自然に湧くのが「ならば .github-private に skills/ ディレクトリも置けば、Agent Skills も組織共有できるのでは？」という発想です。しかし、2026 年 5 月時点でこのアプローチは公式にサポートされていません。

本記事では、.github-private で配布したカスタムエージェントから「どこに置かれた SKILL.md なら参照できるのか」を一次情報ベースで整理し、組織横断での Agent Skills 配布に使える代替策を提示します。

2. TL;DR

• .github-private リポジトリで公式に文書化されたパスは agents/<NAME>.agent.md のみ（ルート直下、.github/ プレフィクスなし）。
• .github-private のルートに skills/ を置いて組織横断で Agent Skills を配布する公式機構は 2026 年 5 月時点で存在しません。
• カスタムエージェントが実行時に参照できるスキルは、クライアント（VS Code）側の chat.agentSkillsLocations が解決するパスに置かれた SKILL.md です。
• chat.agentSkillsLocations は ワークスペース相対パスとチルダ展開のホームディレクトリのみに対応し、他リポジトリ（.github-private など）を直接登録する機構はありません。
• 組織横断で配布したい場合の代替策は (a) プラグイン化（chat.plugins.marketplaces）、(b) VS Code 拡張機能（chatSkills Contribution Point）、(c) ユーザープロファイルへの個別配布の 3 通りです。

3. .github-private リポジトリで公式にサポートされる構造

.github-private は Organization 内に作成する Internal または Private のリポジトリで、組織メンバーから参照可能なカスタムエージェント定義を集約する用途のために用意されています（GitHub Docs: Preparing to use custom agents 参照）。

3.1 公式テンプレートのディレクトリツリー

docs/custom-agents-template リポジトリで提示されている構造はシンプルです。

your-org/.github-private/
├── README.md
└── agents/
    ├── docs-writer.agent.md
    ├── code-reviewer.agent.md
    └── security-auditor.agent.md

ルート直下の agents/ のみが公式に解釈されます。.github/agents/ のような .github/ プレフィクスを付けたパスはサポート対象外です（Custom agents configuration）。

3.2 .github と .github-private の違い

両者はよく混同されますが、目的・公開範囲ともに異なります。

項目	.github	.github-private
主用途	コミュニティヘルスファイル（CONTRIBUTING.md、Issue テンプレート 等）	カスタムエージェントの組織共有
公開範囲	Public 必須	Internal または Private（Public 不可）
解釈されるパス	.github/、ルート、docs/	ルート直下の agents/ のみ
Agent Skills 配布	非対応	非対応（本記事の主題）

4. カスタムエージェントから参照できるスキル探索パス

ここが本記事の核心です。「エージェントが置かれている場所」と「スキルの解決元」は別レイヤーです。.github-private から呼び出されたエージェントであっても、スキルは実行クライアント（VS Code）側の探索パスから解決されます。

4.1 Agent Skills の探索パス一覧

VS Code の Copilot 拡張機能が認識するパスは次のとおりです（VS Code: Use Agent Skills、Copilot settings reference）。

スコープ	パス
ワークスペース（GitHub）	.github/skills/<name>/SKILL.md
ワークスペース（Claude）	.claude/skills/<name>/SKILL.md
ワークスペース（汎用）	.agents/skills/<name>/SKILL.md
ユーザープロファイル（Copilot）	~/.copilot/skills/<name>/SKILL.md
ユーザープロファイル（Claude）	~/.claude/skills/<name>/SKILL.md
ユーザープロファイル（汎用）	~/.agents/skills/<name>/SKILL.md
プラグイン	chat.plugins.marketplaces 経由（既定: github/copilot-plugins、github/awesome-copilot）
拡張機能	VS Code 拡張機能（package.json の contributes.chatSkills）。パス例: <extension-root>/skills/<name>/SKILL.md。拡張機能のインストール時に自動登録され、コピー処理不要

補足:

• .github-private リポジトリはこの探索対象に含まれません。組織レベルで配布できるのはカスタムエージェント（agents/<NAME>.agent.md）のみで、Agent Skills は対象外です。
• Personal skills の 3 パス（~/.copilot/skills/、~/.claude/skills/、~/.agents/skills/）は公式に等価サポートされていますが、実機で広く利用されているのは ~/.agents/skills/（ベンダー非依存）です。~/.copilot/skills/ の実利用例は現時点で限定的です。
• monorepo では chat.useCustomizationsInParentRepositories を有効化すると、親リポジトリ側のカスタマイズ設定やスキルも探索されます。
• 上記の SVG 図には拡張機能（chatSkills Contribution Point）レイヤーが表現されていませんが、同じくクライアント側レイヤーの探索点として機能します（詳細は第 6.2 節）。

4.2 chat.agentSkillsLocations の制約

追加の探索パスは settings.json の chat.agentSkillsLocations で指定できます。

{
  "chat.agentSkillsLocations": {
    ".github/skills": true,
    ".agents/skills": true,
    "~/.copilot/skills": true
  }
}

ただし、サポートされるのは次の 2 種類のみです。

• ワークスペース相対パス（例: .github/skills、docs/skills）
• チルダ展開のホームディレクトリ（例: ~/.copilot/skills）

https://github.com/your-org/.github-private/skills のような URL 直接指定や別リポジトリへの参照は不可 です。設定が false の場合は明示的に無効化されます。

4.3 .agent.md と SKILL.md の frontmatter は別物（混同回避）

「.agent.md の frontmatter にスキル名を書けば、そのスキルだけを読み込ませられるのでは？」という発想もありますが、これは .agent.md 側と SKILL.md 側の frontmatter キーを混同したものです。両者は定義されている仕様が別で、互いに参照し合うキーもありません。

.agent.md（カスタムエージェント）側 frontmatter キー

Custom agents configuration で定義されているのは主に次のキーです。

• name、description、target、tools、model、disable-model-invocation、user-invocable、infer、mcp-servers、metadata など

スキル名を直接列挙する公式項目は存在しません。

SKILL.md（Agent Skills）側 frontmatter キー

Agent Skills specification で定義されているのは次のキーです。

• name、description、argument-hint、user-invocable、disable-model-invocation、context（experimental）

これらはスキル自身のメタデータであり、.agent.md から名前指定で呼び出すためのものではありません。

スキル選択はプログレッシブローディングで自動化

スキルは Copilot がプログレッシブローディングで自動選択します。

1. Discovery: 各スキルの name と description から関連度を判定。
2. Instructions: 関連と判断した SKILL.md 本文を読み込み。
3. Resource access: 参照先のファイルやスクリプトをオンデマンド取得。

つまり、「カスタムエージェントが特定のスキルを使う」のではなく「クライアントが認識しているスキル群の中から、Copilot が文脈に応じて自動マッチングする」 のが正確な振る舞いです。

5. なぜ .github-private に skills/ を置けないのか

理由は単純で、公式ドキュメントに書かれていないからです。.github-private の解釈ルールを定義しているのは GitHub 側のサーバーロジックと VS Code 拡張のクライアントロジックですが、いずれも次の通りです。

• Copilot customization cheat sheet には .github-private の項目に agents/<NAME>.agent.md のみが列挙されている。
• Custom agents configuration でも .github-private 由来のロード対象は agents に限定。
• 公式ドキュメント上、VS Code クライアントが .github-private から取得対象として認識するのは agents/ 配下のみであり、skills/ を組織横断で同期する公式機構は公開されていません。

仮に skills/ ディレクトリを作っても、各メンバーの VS Code がそのリポジトリをローカルにチェックアウトしていない限り、SKILL.md を発見する手段がないということです。

5.1 組織レベル配布設定の対比

カスタムエージェントと Agent Skills を並べると、公式に存在する「組織レベル配布を可能にする設定キー」に明確な差があります。

配布対象	組織レベル配布の公式設定キー	サポート
Custom agents	github.copilot.chat.organizationCustomAgents.enabled	あり
Agent Skills	（同等の組織レベル配布設定キーは存在しない）	なし

この非対称性が、.github-private でエージェントは共有できてもスキルは共有できない根本原因です。

6. 組織横断で Agent Skills を共有する代替策

Agent Skills は agentskills.io で公開されたオープン標準として仕様が公開されています。参照実装に github/awesome-copilot、anthropics/skills があるため、配布フォーマット設計の参考にしてください。

公式機構がない以上、「組織で配布する／クライアントが自動取得する」 という二段の要件を別の仕組みで満たす必要があります。代替策は次の 3 つです。

6.1 プラグイン化（最推奨）

Agent Plugins は Skills / Agent / Hooks / MCP サーバーを 1 リポジトリにまとめて配布できる仕組みです。VS Code の chat.plugins.marketplaces で社内マーケットプレイスを追加し、メンバーがプラグインをインストールすればスキルが自動的に利用可能になります。

{
  "chat.plugins.marketplaces": ["your-org/copilot-plugins"]
}

• メリット: スキル・エージェント・Hooks・MCP を一括配布、バージョン管理が容易、Configure Skills から ON/OFF 可能。
• デメリット: マーケットプレイスリポジトリの新規構築が必要、Hooks や MCP を含む場合は信頼性の確認運用が必須。

6.2 VS Code 拡張機能（chatSkills Contribution Point）

VS Code には Agent Skills を拡張機能から提供するための公式 Contribution Point contributes.chatSkills が用意されています。package.json で SKILL.md のパスを宣言するだけで、拡張機能のインストール時に自動的に登録され、別途コピー処理を実装する必要はありません（Use Agent Skills in VS Code – Contribute skills from extensions）。

package.json 登録例

{
  "contributes": {
    "chatSkills": [{ "path": "./skills/my-skill/SKILL.md" }]
  }
}

プロパティは次の 2 つです。

• path（必須）: SKILL.md への相対パス。親ディレクトリ名は SKILL.md の name フィールドと一致させる必要があります。
• when（任意）: 有効化条件。特定の言語・設定・コンテキストに紐づけて条件付きで有効化できます。

ディレクトリ構造

拡張機能のルートに skills/<name>/SKILL.md を配置します。SKILL.md 本体は Agent Skills specification (agentskills.io) に準拠して記述します。

extension-root/
├── package.json
└── skills/
    └── my-skill/           # ディレクトリ名は SKILL.md の `name` と一致必須
        └── SKILL.md

• メリット: 公式 Contribution Point 経由で登録され、アクティベーション時のコピー処理が不要。拡張機能の更新で自動反映され、Marketplace（社内 / 公開）で配布可能。when 句で条件付き有効化も可能。
• デメリット: 拡張機能のリリースサイクルに依存。Marketplace 配布の準備（署名・公開フロー）にコストがかかる。

6.3 ユーザープロファイルへの個別配布

各メンバーが ~/.agents/skills/、~/.claude/skills/、~/.copilot/skills/ のいずれかに SKILL.md をコピーする方法です。Git リポジトリに置いてセットアップスクリプトで配布するのが現実的です。

実機で広く利用されているのは ~/.agents/skills/（ベンダー非依存）で、組織標準にする場合もこのパスを主に推奨します。~/.claude/skills/ は Claude Code との互換用、~/.copilot/skills/ は公式サポートされていますが実利用例は限定的です。

~/.agents/skills/                # ベンダー非依存。本パスを主に推奨
├── security-review/
│   └── SKILL.md
└── db-migration/
    ├── SKILL.md
    └── migration-template.sql

代替として、Claude Code 併用環境では ~/.claude/skills/、Copilot 専用としたい場合は ~/.copilot/skills/ も同等にサポートされています。

• メリット: 仕組みが単純、社内向けのスクリプト 1 本で展開可能。
• デメリット: 更新の伝搬が手動、メンバーごとのスキルバージョンがズレる、退職者の後始末が必要。

7. 推奨ディレクトリ構成

実運用で推奨する構成は、.github-private をエージェント専用に保ち、スキルは別途プラグインリポジトリで管理するというパターンです。

7.1 .github-private 側（最小構成）

your-org/.github-private/
├── README.md
└── agents/
    ├── docs-writer.agent.md
    ├── code-reviewer.agent.md
    └── security-auditor.agent.md

各 .agent.md の指示文の中で「スキルが利用可能ならそれに従う」程度の記述に留め、特定スキル名のハードコードは避けるのがおすすめです。

7.2 スキル配布用プラグインリポジトリ側

your-org/copilot-plugins/                # マーケットプレイスリポジトリ
├── README.md
└── plugins/
    └── security-toolkit/
        ├── plugin.json
        └── skills/
            ├── security-review/
            │   ├── SKILL.md
            │   └── checklist.md
            └── threat-modeling/
                └── SKILL.md

メンバー側のワークスペース settings.json（または ~/.vscode/settings.json）でマーケットプレイスを有効化します。

{
  "chat.plugins.marketplaces": ["your-org/copilot-plugins"]
}

これでカスタムエージェント（.github-private 由来）と Agent Skills（プラグイン由来）を 別リポジトリで分離管理しつつ、両者をクライアント側で統合できます。

8. 注意点・制限事項

• .github-private は Internal または Private 必須 です。.github（コミュニティヘルス用、Public 必須）とは別物として扱ってください。
• 既存の .chatmode.md ファイルは公式に .agent.md へのリネームが推奨されています（Custom agents in VS Code）。
• 組織レベルカスタムエージェントを利用するには、Organization Owner が AI controls 設定で機能を有効化する必要があります（VS Code 側の設定キー: github.copilot.chat.organizationCustomAgents.enabled、既定 true。Preparing to use custom agents）。
• chat.agentSkillsLocations は公式 Copilot settings reference で ワークスペース相対パスとチルダ展開のみ サポートと明記されており、絶対パスや URL は対象外です。
• プラグインや Hooks をローカルでコード実行させる場合は、プラグインリポジトリの信頼性確認を CI / コードオーナー設定で担保してください。

9. まとめ

.github-private のカスタムエージェントから参照できる Agent Skills は、クライアント（VS Code）側の探索パスに存在するスキルだけです。.github-private 自体に skills/ を置いても、現時点では公式に同期される機構がありません。

組織横断で Agent Skills を配布したい場合は、プラグイン化（最推奨）／拡張機能経由／ユーザープロファイル配布 のいずれかを選ぶことになります。エージェント定義は .github-private、スキル定義はプラグインリポジトリ、とレイヤーを分けて管理するのが、スケールしやすい現実解です。

GitHub からは今後、.github-private で skills/ を直接配布する公式機構が追加される可能性もあります。リリースノートと VS Code 拡張のアップデートを継続的にウォッチしていきましょう。

参考リンク

• Custom agents in VS Code
• Use Agent Skills in VS Code
• GitHub Copilot in VS Code settings reference
• VS Code Contribution Points (contributes.chatSkills)
• Creating custom agents for Copilot cloud agent (GitHub Docs)
• Custom agents configuration (GitHub Docs)
• Copilot customization cheat sheet (GitHub Docs)
• Preparing to use custom agents in your organization (GitHub Docs)
• Agent Skills specification (agentskills.io)
• docs/custom-agents-template (GitHub)
• github/awesome-copilot (GitHub)
• anthropics/skills (GitHub)

関連記事

• Custom Agent と Agent Skills の実践セットアップ
• GitHub 組織の設定共有ガイド — .github / .github-private の使い分け
• Agent Plugins でカスタマイズをパッケージ化する
• Markdown でカスタマイズする実践ガイド

---

この記事の執筆にあたり、AI の支援を受けています。