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> タグに何が注入されているかで認識状態を判定

References

• Custom agents in VS Code

• Subagents in VS Code

• Customize AI in VS Code