## 1. はじめに：よくある誤解 GitHub Organization に `.github-private` リポジトリを作って `agents/` 配下にカスタムエージェントを置けば、組織のメンバー全員がそのエージェントを利用できる——ここまでは [GitHub 公式ドキュメント](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents) に記載のある正しい挙動です。ここで自然に湧くのが「**ならば `.github-private` に `skills/` ディレクトリも置けば、Agent Skills も組織共有できるのでは？**」という発想です。しかし、2026 年 5 月時点でこのアプローチは**公式にサポートされていません**。本記事では、`.github-private` で配布したカスタムエージェントから「どこに置かれた SKILL.md なら参照できるのか」を一次情報ベースで整理し、組織横断での Agent Skills 配布に使える代替策を提示します。 ## 2. TL;DR - `.github-private` リポジトリで公式に文書化されたパスは **`agents/.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](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) 参照）。 ### 3.1 公式テンプレートのディレクトリツリー [`docs/custom-agents-template`](https://github.com/docs/custom-agents-template) リポジトリで提示されている構造はシンプルです。 ```text 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](https://docs.github.com/en/copilot/reference/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）側の探索パス**から解決されます。 ![.github-private のカスタムエージェントとクライアント側 Agent Skills 探索パスのレイヤー関係](https://uraniwaistr20230915.blob.core.windows.net/images/2026/05/17/uploaded_1779026185315_2026-05-11-github-copilot-private-org-agent-skills-path-layers.svg) ### 4.1 Agent Skills の探索パス一覧 VS Code の Copilot 拡張機能が認識するパスは次のとおりです（[VS Code: Use Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills)、[Copilot settings reference](https://code.visualstudio.com/docs/copilot/reference/copilot-settings)）。 | スコープ | パス | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ワークスペース（GitHub） | `.github/skills//SKILL.md` | | ワークスペース（Claude） | `.claude/skills//SKILL.md` | | ワークスペース（汎用） | `.agents/skills//SKILL.md` | | ユーザープロファイル（Copilot） | `~/.copilot/skills//SKILL.md` | | ユーザープロファイル（Claude） | `~/.claude/skills//SKILL.md` | | ユーザープロファイル（汎用） | `~/.agents/skills//SKILL.md` | | プラグイン | `chat.plugins.marketplaces` 経由（既定: `github/copilot-plugins`、`github/awesome-copilot`） | | 拡張機能 | VS Code 拡張機能（`package.json` の `contributes.chatSkills`）。パス例: `/skills//SKILL.md`。拡張機能のインストール時に自動登録され、コピー処理不要 | > **補足**: > > - `.github-private` リポジトリはこの探索対象に含まれません。組織レベルで配布できるのはカスタムエージェント（`agents/.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` で指定できます。 ```json { "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](https://docs.github.com/en/copilot/reference/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](https://agentskills.io/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](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) には `.github-private` の項目に **`agents/.agent.md` のみ**が列挙されている。 - [Custom agents configuration](https://docs.github.com/en/copilot/reference/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](https://agentskills.io/) で公開されたオープン標準として仕様が公開されています。参照実装に [github/awesome-copilot](https://github.com/github/awesome-copilot)、[anthropics/skills](https://github.com/anthropics/skills) があるため、配布フォーマット設計の参考にしてください。公式機構がない以上、**「組織で配布する／クライアントが自動取得する」** という二段の要件を別の仕組みで満たす必要があります。代替策は次の 3 つです。 ### 6.1 プラグイン化（最推奨） [Agent Plugins](2026-04-12-github-copilot-plugins.md) は Skills / Agent / Hooks / MCP サーバーを 1 リポジトリにまとめて配布できる仕組みです。VS Code の `chat.plugins.marketplaces` で社内マーケットプレイスを追加し、メンバーがプラグインをインストールすればスキルが自動的に利用可能になります。 ```json { "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`](https://code.visualstudio.com/api/references/contribution-points) が用意されています。`package.json` で `SKILL.md` のパスを宣言するだけで、拡張機能のインストール時に自動的に登録され、別途コピー処理を実装する必要はありません（[Use Agent Skills in VS Code – Contribute skills from extensions](https://code.visualstudio.com/docs/copilot/customization/agent-skills)）。 #### `package.json` 登録例 ```json { "contributes": { "chatSkills": [{ "path": "./skills/my-skill/SKILL.md" }] } } ``` プロパティは次の 2 つです。 - `path`（必須）: `SKILL.md` への相対パス。**親ディレクトリ名は `SKILL.md` の `name` フィールドと一致**させる必要があります。 - `when`（任意）: 有効化条件。特定の言語・設定・コンテキストに紐づけて条件付きで有効化できます。 #### ディレクトリ構造拡張機能のルートに `skills//SKILL.md` を配置します。`SKILL.md` 本体は [Agent Skills specification (agentskills.io)](https://agentskills.io/specification) に準拠して記述します。 ```text 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/` は公式サポートされていますが実利用例は限定的です。 ```text ~/.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` 側（最小構成） ```text your-org/.github-private/ ├── README.md └── agents/ ├── docs-writer.agent.md ├── code-reviewer.agent.md └── security-auditor.agent.md ``` 各 `.agent.md` の指示文の中で「スキルが利用可能ならそれに従う」程度の記述に留め、特定スキル名のハードコードは避けるのがおすすめです。 ### 7.2 スキル配布用プラグインリポジトリ側 ```text 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`）でマーケットプレイスを有効化します。 ```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](https://code.visualstudio.com/docs/copilot/customization/custom-agents)）。 - 組織レベルカスタムエージェントを利用するには、**Organization Owner が AI controls 設定で機能を有効化**する必要があります（VS Code 側の設定キー: `github.copilot.chat.organizationCustomAgents.enabled`、既定 `true`。[Preparing to use custom agents](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents)）。 - `chat.agentSkillsLocations` は公式 [Copilot settings reference](https://code.visualstudio.com/docs/copilot/reference/copilot-settings) で **ワークスペース相対パスとチルダ展開のみ** サポートと明記されており、絶対パスや 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](https://code.visualstudio.com/docs/copilot/customization/custom-agents) - [Use Agent Skills in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills) - [GitHub Copilot in VS Code settings reference](https://code.visualstudio.com/docs/copilot/reference/copilot-settings) - [VS Code Contribution Points (`contributes.chatSkills`)](https://code.visualstudio.com/api/references/contribution-points) - [Creating custom agents for Copilot cloud agent (GitHub Docs)](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents) - [Custom agents configuration (GitHub Docs)](https://docs.github.com/en/copilot/reference/custom-agents-configuration) - [Copilot customization cheat sheet (GitHub Docs)](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) - [Preparing to use custom agents in your organization (GitHub Docs)](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) - [Agent Skills specification (agentskills.io)](https://agentskills.io/specification) - [docs/custom-agents-template (GitHub)](https://github.com/docs/custom-agents-template) - [github/awesome-copilot (GitHub)](https://github.com/github/awesome-copilot) - [anthropics/skills (GitHub)](https://github.com/anthropics/skills) ## 関連記事 - [Custom Agent と Agent Skills の実践セットアップ](2026-04-12-github-copilot-agent-skills.md) - [GitHub 組織の設定共有ガイド — `.github` / `.github-private` の使い分け](2026-04-02-github-org-sharing.md) - [Agent Plugins でカスタマイズをパッケージ化する](2026-04-12-github-copilot-plugins.md) - [Markdown でカスタマイズする実践ガイド](2026-04-11-github-copilot-markdown-customization.md) --- _この記事の執筆にあたり、AI の支援を受けています。_

タグ: VS Code

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