SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsvscode-custom-agents

vscode-custom-agents

Agents & models

View repository

Updated 10-15 16:46

About this skill

VS Code Custom Agents — Placement, Design, Access Control

When to Use

Action Triggers
Create Creating a new .agent.md , setting up a multi-agent configuration
Debug "Agent not found" error, subagent invocation failure, not appearing in the picker
Review Frontmatter validity check, access control design review

Placement Rules (Critical)

.github/agents/ is scanned only directly under

✅ 認識される
.github/agents/
├── orchestrator.agent.md
├── coding.executor.md
└── quality.reviewer.md

❌ 認識されない
.github/agents/
├── executors/
│   └── coding.executor.md    ← 無視される
└── reviewers/
    └── quality.reviewer.md   ← 無視される

Basis: VS Code official documentation (as of 2026-02-15) "VS Code detects any .md files in the .github/agents folder of your workspace as custom agents." No mention of recursive scanning of subdirectories. Empirical testing also confirmed it is not supported.

Placement Location Options

Location Purpose
.github/agents/ (workspace) Team sharing. Valid only in that workspace
User profile Personal use. Valid in all workspaces
chat.agentFilesLocations setting Specify additional paths. Can also be used to specify subfolders

File Extension

Location Extension
.github/agents/ .agent.md or .md(both are recognized)
.claude/agents/ .md(Claude Code compatible)

Access Control (3 Levels)

frontmatter property

property default Effect
user-invokable true false → Hidden from the picker (dropdown)
disable-model-invocation false true → Not called as a subagent by other agents
agents (parent side) * (allow all) List of specific agent names → Only those subagents are allowed

Important: agents When explicitly listed in the disable-model-invocation: true can be overridden.

Pattern Quick Reference

# 1. ユーザーが直接呼ぶ + サブエージェントとしても呼ばれる（デフォルト）
user-invokable: true    # (省略可)

# 2. サブエージェント専用（ピッカー非表示）
user-invokable: false

# 3. ユーザー専用（他エージェントから呼ばれない）
disable-model-invocation: true

# 4. 特定の親からのみ呼ばれるサブエージェント
user-invokable: false
disable-model-invocation: true
# → 親側の agents リストに明示して呼ぶ

⚠️ Deprecated property

Old New Migration Method
infer: true user-invokable: true (default) Delete or replace the line
infer: false user-invokable: false Replace
target: vscode — Delete (not needed)

Multi-Agent Design Patterns

Orchestrator + Workers pattern

# 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"]
---

Points:

  • orchestrator に agent Subagent invocation will not work unless the tool is included
  • agents Restrict which subagents can be called via the list
  • agents: [] Prohibit use of all subagents with
  • agents: '*' Allow all (default) with

Troubleshooting

Symptom Cause Remedy
Agent does not appear in the picker Placed in a subfolder .github/agents/ Move directly under
Agent does not appear in the picker user-invokable: false OK if intentional. If changing it, true に
runSubagent で "not found" File is not recognized by VS Code Check whether it is placed directly under
Subagent is not called Add to the parent agent no tools tools に "agent" Add
Unintended agent is called agents List not specified On the parent side, agents: [...] explicitly

Debugging method

  1. Chat Diagnostics: Right-click in the chat view → Check the list of recognized agents in Diagnostics
  2. runSubagent test: Call the sub-agent directly and check whether the custom instructions are reflected in the response
  3. Check session context: <agents> Determine the recognition status by what is injected into the tag

References