VS Code Custom Agents — 配置・設計・アクセス制御
vscode-custom-agents
VS Code カスタムエージェントの配置ルール・アクセス制御・マルチエージェント設計のベストプラクティス。Triggers on 'custom agent', 'agent not found', 'subagent', 'user-invokable', 'エージェント設計', 'ピッカー'.
SKILL.md
Full skill instructions
VS Code Custom Agents — 配置・設計・アクセス制御
When to Use
| Action | Triggers |
|---|---|
| Create | 新しい .agent.md 作成、マルチエージェント構成セットアップ |
| Debug | "Agent not found" エラー、サブエージェント呼び出し失敗、ピッカーに表示されない |
| Review | frontmatter の妥当性チェック、アクセス制御の設計レビュー |
配置ルール（Critical）
.github/agents/ は直下のみスキャンされる
✅ 認識される
.github/agents/
├── orchestrator.agent.md
├── coding.executor.md
└── quality.reviewer.md
❌ 認識されない
.github/agents/
├── executors/
│ └── coding.executor.md ← 無視される
└── reviewers/
└── quality.reviewer.md ← 無視される
根拠: VS Code 公式ドキュメント (2026-02-15 時点)
"VS Code detects any .md files in the .github/agents folder of your workspace as custom agents."サブディレクトリの再帰スキャンについて明記なし。実証テストでも非対応を確認。
配置場所の選択肢
| 場所 | 用途 |
|---|---|
.github/agents/ (ワークスペース) | チーム共有。そのワークスペースでのみ有効 |
| ユーザープロファイル | 個人用。全ワークスペースで有効 |
chat.agentFilesLocations 設定 | 追加パスを指定。サブフォルダ指定にも使える |
ファイル拡張子
| 場所 | 拡張子 |
|---|---|
.github/agents/ | .agent.md または .md（どちらも認識される） |
.claude/agents/ | .md（Claude Code 互換） |
アクセス制御（3段階）
frontmatter プロパティ
| プロパティ | デフォルト | 効果 |
|---|---|---|
user-invokable | true | false → ピッカー (ドロップダウン) に非表示 |
disable-model-invocation | false | true → 他エージェントからサブエージェントとして呼ばれない |
agents (親側) | * (全許可) | 特定エージェント名のリスト → そのサブエージェントのみ許可 |
重要:
agentsリストに明示するとdisable-model-invocation: trueをオーバーライドできる。
パターン早見表
# 1. ユーザーが直接呼ぶ + サブエージェントとしても呼ばれる（デフォルト）
user-invokable: true # (省略可)
# 2. サブエージェント専用（ピッカー非表示）
user-invokable: false
# 3. ユーザー専用（他エージェントから呼ばれない）
disable-model-invocation: true
# 4. 特定の親からのみ呼ばれるサブエージェント
user-invokable: false
disable-model-invocation: true
# → 親側の agents リストに明示して呼ぶ
⚠️ Deprecated プロパティ
| 旧 | 新 | 移行方法 |
|---|---|---|
infer: true | user-invokable: true (デフォルト) | 行を削除するか置換 |
infer: false | user-invokable: false | 置換 |
target: vscode | — | 削除（不要） |
マルチエージェント設計パターン
Orchestrator + Workers パターン
# orchestrator.agent.md
---
name: orchestrator
user-invokable: true
disable-model-invocation: true
tools: ["codebase", "terminal", "agent"] # "agent" が必須
agents:
- coding-executor
- quality-reviewer
- auditor
---
# coding.executor.md
---
name: coding-executor
user-invokable: false
tools: ["codebase", "terminal"]
---
ポイント:
- orchestrator に
agentツールを含めないとサブエージェント呼び出しが機能しない agentsリストで呼び出せるサブエージェントを制限するagents: []で全サブエージェント利用を禁止agents: '*'で全許可（デフォルト）
トラブルシューティング
| 症状 | 原因 | 対処 |
|---|---|---|
| エージェントがピッカーに出ない | サブフォルダに配置 | .github/agents/ 直下に移動 |
| エージェントがピッカーに出ない | user-invokable: false | 意図的なら OK。変更するなら true に |
runSubagent で "not found" | ファイルが VS Code に認識されていない | 直下に配置されているか確認 |
| サブエージェントが呼ばれない | 親に agent ツールがない | tools に "agent" を追加 |
| 意図しないエージェントが呼ばれる | agents リスト未指定 | 親側で agents: [...] を明示 |
デバッグ方法
- Chat Diagnostics: チャットビューで右クリック → Diagnostics で認識されているエージェント一覧を確認
runSubagentテスト: サブエージェントを直接呼び出して応答にカスタム指示が反映されているか確認- セッションコンテキスト確認:
<agents>タグに何が注入されているかで認識状態を判定