CowboyLogic/ai-dev / skills/agent-creator-copilot
agent-creator-copilot
VerifiedGuide for creating custom agents for GitHub Copilot (cloud agent on GitHub.com, Copilot CLI, VS Code, and other IDEs). Use this when building custom agent profiles (.agent.md files), configuring tools, models, handoffs, subagents, hooks, or MCP server integrations for Copilot.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.8 KB |
| SKILL.md | skill md | 12.2 KB |
| references/cloud-agent-with-mcp-example.agent.md | markdown | 2.9 KB |
| references/frontmatter-reference.md | markdown | 31.4 KB |
| references/prompt-writing-guide.md | markdown | 3.6 KB |
| references/tools-reference.md | markdown | 6.5 KB |
| references/user-profile-agent-example.agent.md | markdown | 1.4 KB |
| references/workspace-agent-example.agent.md | markdown | 1.7 KB |
references/frontmatter-reference.md
View on GitHub# Frontmatter Reference — Custom Agent Profiles
Reference for the YAML frontmatter properties in custom agent profiles (`.agent.md`). Load this file when writing or modifying agent frontmatter.
**Sources (last verified November 2026, against GitHub Copilot CLI v1.0.105):**
- GitHub configuration reference: <https://docs.github.com/en/copilot/reference/custom-agents-configuration>
- VS Code: <https://code.visualstudio.com/docs/agent-customization/custom-agents>
- VS Code custom agent file reference: <https://code.visualstudio.com/docs/agents/reference/custom-agent-file-reference>
- VS Code subagents: <https://code.visualstudio.com/docs/agents/run/subagents>
- VS Code customization migration: <https://code.visualstudio.com/docs/agent-customization/migrate-customizations>
- VS Code hooks: <https://code.visualstudio.com/docs/agent-customization/hooks>
- GitHub hooks reference (agent-scoped hooks, Copilot CLI): <https://docs.github.com/en/copilot/reference/hooks-reference#agent-scoped-hooks>
- Copilot CLI: <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference>
- Models: <https://docs.github.com/en/copilot/reference/ai-models/supported-models>
---
## Surfaces
Custom agents are used by several products that each read the profile differently:
- **Copilot cloud agent on GitHub.com**: agents tab/panel, issue assignment, pull requests
- **GitHub Copilot app**: listed by GitHub as a place custom agents are available
- **GitHub Copilot CLI**: `/agent`, `--agent`, or inferred delegation to a subagent
- **VS Code** (and JetBrains IDEs, Eclipse, Xcode, which are in public preview for custom agents): the agents dropdown in chat. VS Code has several harnesses (**Local**, **Copilot**, Claude, Codex, Cloud) and the selected harness decides which fields and tool names take effect; handoffs work only with **Local**. Agent-scoped hooks run in Local, and the Copilot harness supports them too, but VS Code currently drops `hooks` when it converts plugin-provided agents (see [`hooks`](#hooks)).
Every surface ignores tool names it does not recognize, and GitHub.com explicitly ignores the IDE-only `argument-hint` and `handoffs` properties.
---
## Platform Compatibility Overview
| Property | VS Code / IDEs | GitHub.com cloud agent | Copilot CLI |
|---|---|---|---|
| `name` | ✅ | ✅ | ✅ |
| `description` | ✅ (header optional) | ✅ **Required** | ✅ **Required** |
| `target` | ✅ | ✅ | Not listed in CLI reference |
| `tools` | ✅ (aliases, tool names; user-defined tool sets are deprecated) | ✅ (aliases, MCP tools) | ✅ |
| `model` | ✅ string or array | ⚠️ See [`model`](#model) | ✅ string |
| `user-invocable` | ✅ | ✅ | Not listed in CLI reference |
| `disable-model-invocation` | ✅ (blocks subagent use unless a coordinator lists the agent in `agents`) | ✅ (blocks auto-selection) | Not listed in CLI reference |
| `infer` | Deprecated | Retired | ✅ Listed as active (see [`infer`](#infer-retired--deprecated)) |
| `argument-hint` | ✅ | ❌ Ignored | Not listed |
| `handoffs` | ✅ Local harness | ❌ Ignored | Not listed |
| `agents` | ✅ | Not listed | Not listed |
| `hooks` | ✅ Local harness; the Copilot harness supports them but plugin-agent conversion omits the field (see [`hooks`](#hooks)) | Not listed | ✅ Agent-scoped hooks (v1.0.97), documented in the hooks reference; not in the CLI frontmatter table |
| `mcp-servers` | ❌ Not used (only passed through for `target: github-copilot`) | ✅ | ✅ |
| `metadata` | ❌ Not used | ✅ | Not listed |
| `reasoning-effort` | ✅ Copilot harness | Not listed | Not listed (the CLI uses `reasoningEffort`) |
| `include-custom-instructions` | ⚠️ Copilot-harness editor schema field only; not forwarded when converting plugin-provided agents (see [VS Code Copilot-harness schema fields](#vs-code-copilot-harness-schema-fields)) | Not listed | ✅ |
| `model-policy` | ⚠️ Copilot-harness editor schema field (`preferred` or `required`); not forwarded when converting plugin-provided agents | Not listed | Not listed (the CLI uses `modelPolicy`) |
| `deferred-tool-loading` | ⚠️ Copilot-harness editor schema field; not forwarded when converting plugin-provided agents | Not listed | Not listed |
| `strict-tools-list` | ⚠️ Copilot-harness editor schema field; not forwarded when converting plugin-provided agents | Not listed | Not listed |
| `models` | Not listed | Not listed | ✅ |
| `modelPolicy` | Not listed | Not listed | ✅ |
| `reasoningEffort` | Not listed | Not listed | ✅ |
"Not listed" means the surface's docs do not mention the property. It will most likely be ignored, but that is not documented.
> [!NOTE]
> The GitHub configuration reference states its property table applies to "GitHub.com, the Copilot CLI, and supported IDEs (unless otherwise noted)", yet the CLI's own frontmatter table omits `target`, `user-invocable`, `disable-model-invocation`, and `metadata`. Treat those as unverified in the CLI.
---
## All Properties at a Glance
```yaml
---
name: my-agent # display name; defaults to filename
description: What this agent does # required on GitHub.com and CLI
target: vscode # vscode | github-copilot | omit for both
tools: ["read", "search"] # omit = all tools
model: Claude Sonnet 5 # string, or array in VS Code
reasoning-effort: high # VS Code Copilot harness: low | medium | high | xhigh | max
user-invocable: true # show in agent picker (default true)
disable-model-invocation: false # block auto-selection / subagent use, unless a coordinator lists the agent in `agents` (default false)
argument-hint: Paste your spec here # VS Code / IDEs only
agents: ["Researcher", "Reviewer"] # VS Code only: allowed subagents
handoffs: # VS Code / IDEs only
- label: Implement
agent: implementation
prompt: Implement the plan above.
send: false
model: GPT-5.5 (copilot)
hooks: # VS Code (Local harness) and Copilot CLI
PostToolUse:
- type: command
command: "./scripts/format-changed-files.sh"
mcp-servers: # GitHub.com cloud agent and Copilot CLI
my-server:
type: local
command: npx
args: ["-y", "my-mcp-server"]
tools: ["*"]
env:
API_KEY: ${{ secrets.COPILOT_MCP_API_KEY }}
metadata: # GitHub.com only
team: platform
---
```
This block shows syntax only. A real profile should set only the properties its target surfaces use.
---
## Property Reference
### `description` *(Required)*
**Type:** string
**Platforms:** All
Describes the agent's purpose and capabilities. GitHub.com and the CLI use it to decide when to infer/auto-select the agent, and the CLI shows it in the agent list and `task` tool. VS Code shows it as placeholder text in the chat input field.
```yaml
description: Reviews REST API designs for correctness, security, and consistency
```
---
### `name`
**Type:** string
**Default:** filename without `.md` / `.agent.md`
**Platforms:** All
Display name. The filename, not `name`, is the agent's ID for deduplication across levels and for `copilot --agent <id>`. In VS Code, `agents` lists and handoff `agent` values reference agents by name, and subagent names are case-sensitive.
```yaml
name: API Reviewer
```
---
### `target`
**Type:** string
**Values:** `vscode` | `github-copilot` | *(omit for both)*
**Platforms:** GitHub.com, VS Code / IDEs
Restricts which environment uses the profile. Omit it to make the agent available in both. It is not the VS Code harness selector: `github-copilot` names the GitHub.com cloud agent target, not the **Copilot** harness.
```yaml
target: vscode # VS Code and IDEs only
target: github-copilot # GitHub.com cloud agent only
```
---
### `tools`
**Type:** list of strings, or comma-separated string
**Default:** all tools
**Platforms:** All
Filters the tools available to the agent, whether built-in or from MCP servers. See `tools-reference.md` for aliases, VS Code tool names, and MCP namespacing.
```yaml
tools: ["read", "search"] # specific aliases (least privilege)
tools: ["*"] # all tools explicitly
tools: [] # no tools
tools: ["read", "github/*"] # alias + all tools from an MCP server
tools: ["read", "my-server/tool-a"] # alias + one MCP tool
```
In the CLI, including `*` anywhere grants every tool (`["view", "*"]` means all tools).
**Tool list priority (VS Code Local):** when a prompt file and a custom agent both set `tools`, the prompt file's list wins. Other harnesses (such as Copilot) don't load prompt files.
---
### `model`
**Type:** string (all surfaces); string or array (VS Code)
**Default:** inherits the currently selected / session / parent-agent model
```yaml
# VS Code / IDEs: model display name
model: Claude Sonnet 5
# VS Code: prioritized fallback list, tried in order
model: ["Claude Opus 5", "GPT-5.5"]
# Copilot CLI: model ID
model: gpt-5.6-luna
```
**Surface notes:**
- **VS Code:** accepts a model name or a prioritized array (the first available model is used). The VS Code file reference describes the field for the Copilot harness, and Local subagents also use it as part of their model selection order. For subagents, the order is: explicit model from the `runSubagent` call, then the agent's `model`, then the main conversation's model. A subagent model above the main model's cost tier does not run.
- **Copilot CLI:** uses lowercase IDs (the CLI docs show `claude-sonnet-5.5` as the default and list `gpt-5.4`, `gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-luna`, `claude-opus-5.5`, `claude-haiku-5.5`, `claude-haiku-4.5`, `gpt-5.3-codex`, `gemini-3.7-flash`, and `gemini-3.8-flash`, with model IDs case-insensitive; the built-in agents use `claude-sonnet-4.6`, `claude-haiku-4.5`, and `gpt-5.4-mini`). When the session model is `Auto`, subagents always use the resolved session model and ignore this field. See also `models`, `modelPolicy`, and `reasoningEffort` below.
- **GitHub.com cloud agent:** ambiguous. The configuration reference lists `model` without restriction ("Model to use when this custom agent executes"), but the create how-to says `model` applies "if you are creating and using the agent profile in VS Code, JetBrains IDEs, Eclipse, or Xcode". Don't rely on `model` to select the cloud agent's model.
- **Handoff `model`** uses the qualified format `Model Name (vendor)`, for example `GPT-5.5 (copilot)`.
**Current model names (from the supported-models page, October 2026):** GPT-5 mini, GPT-5.3-Codex, GPT-5.4, GPT-5.4 mini, GPT-5.4 nano (only in the Codex VS Code extension, Pro+), GPT-5.5, GPT-5.6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-6 Astra, GPT-6 Luna, GPT-6 Sol, GPT-6.1 Sol, Claude Fable 5, Claude Fable 5.1, Claude Haiku 4.5, Claude Haiku 5.5, Claude Opus 4.8 (and a preview fast mode), Claude Opus 5, Claude Opus 5.5, Claude Sonnet 4.6, Claude Sonnet 5, Claude Sonnet 5.5, Gemini 3.7 Flash, Gemini 3.8 Flash, Gemini 4 Argon, MAI-Code-1.1-Flash, Kimi K3, Grok 4.5–4.7. Availability differs by client. In the page's per-client table, Gemini (including Gemini 4 Argon), Grok, and GPT-5 mini are not available on GitHub.com; Claude Sonnet 4.6 is not available in Eclipse, Xcode, or JetBrains IDEs; the GPT-5.6 models are not available in Eclipse, Xcode, or JetBrains IDEs; and Claude Opus 4.8 fast mode is not available on GitHub.com. GPT-6.1 Sol is listed but doesn't appear in the per-client table.
> [!WARNING]
> Retired models no longer resolve. Retired 2026-10-02: Claude Opus 4.7, Gemini 3.5 Flash, Gemini 3.6 Flash, and Kimi K2.7 Code. MAI-Code-1-Flash was retired 2026-09-10. Retired 2026-09-01: Claude Sonnet 4.5, Claude Opus 4.5, Claude Opus 4.6, Claude Sonnet 4.6 (still available to individual subscribers on annual plans), Gemini 3.1 Pro, and Raptor mini. GPT-5.2 and GPT-5.2-Codex were retired 2026-06-05, and GPT-4.1 on 2026-06-01. Many community examples (including awesome-copilot and VS Code's own doc samples) still pin retired models such as `GPT-4.1`, `GPT-5.2`, or `Claude Sonnet 4.5`. Check the retirement table before copying one.
---
### `models`, `modelPolicy`, `reasoningEffort` *(Copilot CLI only)*
| Property | Type | Description |
|---|---|---|
| `models` | string[] | Models in priority order. The first one the user's plan can access is used; if none resolve, falls back to the session's model. Overrides `model` when both are set. |
| `modelPolicy` | string | `"preferred"` (default) lets `model`/`models` be overridden by a `subagents` override in `~/.copilot/settings.json` or the `/subagents` picker. `"required"` locks dispatch to one of the authored models. |
| `reasoningEffort` | string | Default reasoning effort, for example `"low"`, `"medium"`, `"high"`. Inherits the outer agent's effort when unset. |
Precedence, highest first: explicit per-call value, then the `subagents` override in `~/.copilot/settings.json`, then the agent's `model`/`models`/`reasoningEffort`, then the parent session's value.
---
### VS Code Copilot-harness schema fields
The VS Code custom agent file reference (page dated 10/30/2026) lists these fields as recognized by the Copilot harness editor schema, with completions and validation: `model-policy` (`preferred` or `required`), `deferred-tool-loading` (boolean, load tools on demand), `strict-tools-list` (boolean, omit standard required tools that are not explicitly listed), `include-custom-instructions` (boolean), `github` (an object with `toolsets` and `permissions`), `mcp-servers`, and `hooks`.
Editor schema support does not guarantee runtime support. When VS Code converts agent files to SDK custom-agent configuration, including plugin-provided agents, it does not forward `model-policy`, `mcp-servers`, `github`, `deferred-tool-loading`, `strict-tools-list`, or `include-custom-instructions`. Do not rely on those fields for the runtime behavior of converted agents. The page also says `advancedOptions` is Local-only and not supported by the Copilot schema. The `model-policy` and `include-custom-instructions` fields have separate Copilot CLI semantics (`modelPolicy`, `include-custom-instructions` above) that are not the same claim.
---
### `reasoning-effort` *(VS Code, Copilot harness)*
**Type:** string
**Values:** `low` | `medium` | `high` | `xhigh` | `max`
Reasoning effort for the agent in the Copilot harness. Availability depends on the selected model; see [Thinking effort](https://code.visualstudio.com/docs/agent-customization/language-models#configure-thinking-effort). Copilot CLI agent profiles use `reasoningEffort` instead (above).
```yaml
reasoning-effort: high
```
---
### `include-custom-instructions` *(Copilot CLI only)*
**Type:** boolean
**Default:** `false`
When the agent runs as a **subagent**, include repository instruction files (`copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`). Has no effect when the agent is selected directly (`--agent`, `/agent`, inference), because the session agent already receives them. `--no-custom-instructions` always wins.
```yaml
include-custom-instructions: true
```
---
### `user-invocable`
**Type:** boolean
**Default:** `true`
**Platforms:** GitHub.com, VS Code / IDEs
When `false`, users can't select the agent manually. It can only be used as a subagent or programmatically. In VS Code this controls picker visibility for both the Local and Copilot harnesses. Editing it changes the shared agent definition, not a personal visibility preference.
```yaml
user-invocable: false
```
---
### `disable-model-invocation`
**Type:** boolean
**Default:** `false`
**Platforms:** GitHub.com, VS Code / IDEs
The meaning differs by surface:
- **GitHub.com:** when `true`, the cloud agent will not automatically use this agent based on task context. It must be selected manually. Equivalent to `infer: false`. If both are set, `disable-model-invocation` wins.
- **VS Code:** when `true`, other agents can't invoke this agent as a subagent. An explicit entry in a coordinator's `agents` list overrides it.
```yaml
disable-model-invocation: true
```
| Combination | Effect |
|---|---|
| `user-invocable: false` | Hidden from the picker, still usable as a subagent |
| `disable-model-invocation: true` | Visible in the picker, not auto-selected / not used as a subagent (unless explicitly listed in `agents` in VS Code) |
| Both | Not user-selectable and not auto-invoked. Only reachable via an explicit `agents` entry (VS Code) or programmatically |
---
### `infer` *(Retired / Deprecated)*
**Do not use in new profiles.** GitHub.com marks it retired and VS Code deprecated, replaced by `user-invocable` and `disable-model-invocation`. On GitHub.com, `infer: false` is equivalent to `disable-model-invocation: true` (it does **not** imply `user-invocable: false`).
> [!NOTE]
> The Copilot CLI command reference still lists `infer` (boolean, default `true`, "Allow auto-delegation by the main agent") as an active field and does not list `disable-model-invocation`. If you need to stop CLI auto-delegation, `infer: false` is the only CLI-documented option.
---
### `argument-hint`
**Type:** string
**Platforms:** VS Code / IDEs only. Ignored on GitHub.com.
Hint text shown in the chat input field when the agent is selected in the Local harness.
```yaml
argument-hint: Paste the OpenAPI spec or describe the endpoint to review
```
---
### `agents`
**Type:** list of strings
**Platforms:** VS Code only
Names of agents this agent may invoke as subagents. The `agent` tool must be in `tools`.
```yaml
tools: ["agent", "read", "search"]
agents: ["Codebase Researcher", "Reviewer"]
```
- Omitted or `["*"]`: all available agents (except those with `disable-model-invocation: true`)
- `[]`: no subagents
- Names are case-sensitive
**Nested subagents:** Local subagents can't invoke further subagents unless `chat.subagents.allowInvocationsFromSubagents` is enabled (default `false`, maximum depth five). A self-referential agent lists itself in `agents`.
---
### `handoffs`
**Type:** list of objects
**Platforms:** VS Code / IDEs only (Local harness in VS Code). Ignored on GitHub.com.
Buttons shown after a response completes that switch to another agent with the conversation context and a pre-filled prompt.
| Property | Type | Required | Description |
|---|---|---|---|
| `label` | string | Yes | Button text |
| `agent` | string | Yes | Target agent identifier (built-in agents such as `agent` also work) |
| `prompt` | string | Yes | Prompt to pre-fill when the user selects the handoff (the VS Code file reference marks it required) |
| `send` | boolean | No | `true` auto-submits the prompt; default `false` |
| `model` | string | No | Model for the handoff, in `Model Name (vendor)` format, for example `Claude Sonnet 5 (copilot)` |
```yaml
handoffs:
- label: Start Implementation
agent: implementation
prompt: Implement the plan outlined above, starting with the database layer.
send: false
model: GPT-5.5 (copilot)
- label: Security Review
agent: security-analyst
prompt: Review the implementation above for security vulnerabilities.
send: true
```
Common workflows:
- Planning → Implementation
- Implementation → Code Review
- Write Failing Tests → Write Passing Implementation
---
### `hooks`
**Type:** object (map of event name → list of hook entries)
**Platforms:** VS Code (**Local** harness, and the Copilot harness subject to the conversion limitation below) and **Copilot CLI** (v1.0.97). Not listed for the GitHub.com cloud agent.
Hook commands that run only while this agent is active, in addition to user, workspace, repository, and plugin hooks. The two surfaces document and implement this separately, each with its own settings and event reference:
| | VS Code (Local harness) | Copilot CLI |
|---|---|---|
| Requires | `chat.useHooks` (on by default) and a trusted workspace | Workspace admission for repository and inherited-agent hooks; hook-disable settings, enterprise restrictions, and timeouts still apply |
| Event names | PascalCase: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `SubagentStart`, `SubagentStop`, `Stop` | Runtime names such as `postToolUse` and aliases such as `PostToolUse` |
| Per-platform commands | Local hook format uses `command` with `windows`, `linux`, `osx` overrides (hooks doc) | `command` is the fallback; `windows`, `linux`, `osx` override it; paths resolve from the repository root |
| Subagent `Stop` | The agent's `Stop` hook is treated as `SubagentStop` | The scoped `Stop` (`agentStop`) hooks run at `SubagentStop`; after eight consecutive scoped blocks, further blocks are ignored |
| Not supported | Claude and Codex harnesses; plugin-provided agents converted for the Copilot harness lose the field (below) | Remote or organization-hosted agent definitions |
The VS Code hooks reference also lists a `PreCompact` event for Local hooks; it doesn't state whether agent-scoped hooks accept it, so test before relying on it.
```yaml
hooks:
PostToolUse:
- type: command
command: "./scripts/format-changed-files.sh"
```
VS Code's hooks article says the Copilot harness supports agent-scoped hooks, but VS Code currently omits the `hooks` field when it converts plugin-provided custom agents for that harness, so such an agent can appear and run without its scoped hooks (tracked in [microsoft/vscode#341681](https://github.com/microsoft/vscode/issues/341681)). For an affected agent, keep the definition and treat its hook migration as incomplete; don't move the command to a repository-wide or plugin-wide event, which changes which agents trigger it. The event list may have more entries than shown here: check the [VS Code hooks reference](https://code.visualstudio.com/docs/agents/reference/hooks-reference) and the [GitHub hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference#agent-scoped-hooks) for the complete lists.
---
### `mcp-servers`
**Type:** object
**Platforms:** GitHub.com cloud agent and Copilot CLI. Not used by VS Code or other IDE custom agents.
MCP servers available only to this agent. On GitHub.com it is a YAML form of the repository MCP JSON configuration. In the CLI it uses the same schema as `~/.copilot/mcp-config.json`.
```yaml
mcp-servers:
custom-mcp: # key becomes the tool namespace (custom-mcp/<tool>)
type: local # "stdio" is accepted and mapped to "local"
command: some-command
args: ["--arg1", "--arg2"]
tools: ["*"] # tools the server exposes; ["*"] = all
env:
ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
```
**Secret and variable syntax (GitHub.com):**
| Syntax | Where supported |
|---|---|
| `$COPILOT_MCP_ENV_VAR_VALUE` | Repository MCP JSON and agent YAML |
| `${COPILOT_MCP_ENV_VAR_VALUE}` | Repository MCP JSON and agent YAML (Claude Code syntax) |
| `${COPILOT_MCP_ENV_VAR_VALUE:-default}` | Repository MCP JSON and agent YAML, with default |
| `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` | Agent YAML only |
| `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` | Agent YAML only |
Secrets and variables must be configured as **Agents** secrets/variables at the organization or repository level, and their names **must start with `COPILOT_MCP_`**. Only prefixed secrets and variables are passed to MCP configuration, and they are exposed only to MCP servers, not to the agent's environment.
**Processing order (GitHub.com):** out-of-the-box MCP (for example `github`) → custom agent `mcp-servers` → repository-settings MCP. Each level can override the previous one. Out-of-the-box servers are covered in `tools-reference.md`.
---
### `metadata`
**Type:** object of string name/value pairs
**Platforms:** GitHub.com only. Not used by VS Code or other IDEs.
```yaml
metadata:
team: platform-engineering
owner: dev-productivity
```
---
## Prompt Body References (VS Code)
The Markdown body holds the agent's instructions. Per the VS Code file reference:
- Reference files with Markdown links or `#file:` syntax. Relative paths resolve from the custom agent file; `~` or `~/` refers to the home folder. Use `/` separators so paths stay portable across operating systems.
- In the Local harness, reference a tool with `#tool:<tool-name>`, such as `#tool:web/fetch`.
- When the agent is selected in chat, its body is added after the user's custom instructions and takes precedence if they conflict.
```markdown
Follow the [review checklist](./review-checklist.md).
Use #file:~/copilot/security-guidelines.md for security reviews.
```
---
## Claude Agent Format (`.claude/agents/`)
VS Code and Copilot CLI both load agents from `.claude/agents/` (plain `.md` files in the [Claude sub-agents format](https://code.claude.com/docs/en/sub-agents)). VS Code also reads `~/.claude/agents/` at user level. User-level agents must be in the supported folder on the machine where the selected harness runs (`~/.copilot/agents` for the Copilot harness; `~/.claude/agents` applies only to Anthropic Claude harness sessions); those folders are separate from VS Code profile user data. For Local harness sessions, user-level agents are stored in VS Code profile storage.
| Property | `.agent.md` format | Claude format |
|---|---|---|
| File extension | `.agent.md` | `.md` |
| `name` | Optional | Required |
| `tools` | YAML array | Comma-separated string, for example `"Read, Grep, Glob, Bash"` |
| `disallowedTools` | Not supported | Comma-separated string of blocked tools |
| `model` | Model name or array (see [`model`](#model)) | `sonnet`, `opus`, `haiku`, or `inherit` (default) |
| `permissionMode` | Not listed | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |
| `skills`, `mcpServers`, `memory` | Not listed | Skills to load into the agent's context at startup, MCP servers, and persistent memory scope (`user`, `project`, or `local`) |
| `hooks` | Object (see [`hooks`](#hooks)) | Lifecycle hooks scoped to the agent |
```markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, WebFetch
disallowedTools: Bash, Edit, Write
---
You are a security specialist...
```
The Claude harness implements these fields according to Anthropic's documentation. When the Local harness loads a Claude-format agent, VS Code maps supported Claude tool and model names to their VS Code equivalents; that doesn't make all Claude runtime features available in Local. In the CLI, `.github/agents/` takes precedence over `.claude/agents/` at the same directory level.
---
## Processing Rules
### Naming conflicts
The filename (minus `.md` / `.agent.md`) identifies the agent. The lowest-level configuration wins: repository over organization, organization over enterprise.
**Copilot CLI specifics:** the agent ID is the file's path relative to the `agents` directory with directory separators replaced by `--` (`agents/team/reviewer.agent.md` is `team--reviewer`). Priority, first loaded wins: user (`~/.copilot/agents/`), then project `.github/agents/` (every level from the current directory up to the Git root, deepest first), then project `.claude/agents/`, then directories added with `--add-dir` / `/add-dir`, then plugin agents, then remote organization/enterprise agents. A personal agent therefore overrides a repository agent with the same ID. The `name` field does not affect deduplication: agents with the same `name` but different IDs both load.
### Versioning (GitHub.com)
Versioning follows Git commit SHAs of the profile file. An assigned task uses the latest profile version on the repository and branch, and follow-up interactions in the resulting pull request keep using that same version.
### File detection (VS Code)
VS Code's file-locations table lists `.agent.md` or `.md` files for `.github/agents` and `~/.copilot/agents`; prefer `.agent.md`. The `chat.agentFilesLocations` setting remains supported and is not deprecated (VS Code forwards agents from the extra locations to the Copilot harness), but VS Code recommends native folders because Copilot CLI and the GitHub Copilot app don't read it; the older `chat.modeFilesLocations` setting is deprecated. Legacy `.chatmode.md` files should be renamed to `.agent.md`.
### Moving a Local agent to the Copilot harness (VS Code)
VS Code's migration guide describes what changes when a custom agent that worked in a Local session is used in a Copilot (Agent Host) session:
- The Copilot harness doesn't read custom agents from VS Code profile user data, so user agents need to move to `~/.copilot/agents`. The `chat.agentFilesLocations`, `chat.instructionsFilesLocations`, and `chat.agentSkillsLocations` settings remain supported and not deprecated: VS Code forwards files from those extra locations to Agent Host harnesses including Copilot, but Copilot CLI and the GitHub Copilot app don't read the settings, so the migration list moves agents to `.github/agents` (workspace) or `~/.copilot/agents` (user). Migrated user files aren't included in Settings Sync.
- Prompt files (`*.prompt.md`) aren't loaded in Copilot sessions. The migration converts them to skills with `disable-model-invocation: true`; the prompt's `agent`, `model`, and `tools` aren't carried over.
- Agents that depend on Local tool names, tool sets, or hooks need semantic changes. VS Code has no automatic migration for hooks or tool-set files; user-defined tool sets are deprecated and the Copilot harness doesn't support them, so replace them with tools named in the agent's `tools` list or managed in the **Tools** tab. Local references such as `agent/runSubagent` and `vscode/toolSearch` aren't portable: Copilot delegates with its native `task` tool, and an instruction that names a Local tool doesn't switch automatically. It points to **Migrate with Agent** (which uses Copilot credits) for guided conversions.
---
## Complete Working Examples
### Read-only analyst (VS Code)
```yaml
---
name: API Analyst
description: Reviews REST API specifications for design quality and security. Does not modify code.
tools: ["read", "search", "web"]
model: Claude Sonnet 5
argument-hint: Paste the OpenAPI spec or describe the endpoint
target: vscode
handoffs:
- label: Implement Changes
agent: api-dotnet
prompt: Implement the API changes recommended by the analyst.
send: false
---
```
### Orchestrator with subagents (VS Code)
```yaml
---
name: Project Lead
description: Coordinates planning, implementation, and review across specialized agents.
tools: ["agent", "read", "search"]
agents: ["Implementation Planner", "Code Reviewer", "Security Analyst"]
target: vscode
---
```
### Hidden utility subagent (VS Code)
```yaml
---
name: Terraform Validator
description: Validates Terraform plans. Invoked only as a subagent, not shown in the picker.
tools: ["read", "execute"]
user-invocable: false
---
```
Leave `disable-model-invocation` unset here. Setting it to `true` would stop coordinators from delegating to this agent unless they list it explicitly in `agents`.
### Cloud agent with MCP (GitHub.com)
```yaml
---
name: data-pipeline-agent
description: Manages ETL pipelines using the internal data platform API.
tools: ["read", "edit", "search", "data-platform/list-pipelines", "data-platform/run-pipeline", "github/*"]
target: github-copilot
mcp-servers:
data-platform:
type: local
command: npx
args: ["-y", "@company/data-platform-mcp"]
tools: ["*"]
env:
API_TOKEN: ${{ secrets.COPILOT_MCP_DATA_PLATFORM_TOKEN }}
ENVIRONMENT: ${{ vars.COPILOT_MCP_DEPLOY_ENV }}
metadata:
team: data-engineering
---
```
### CLI subagent with model policy (Copilot CLI)
```yaml
---
name: test-runner
description: Runs the test suite and summarizes failures. Use when tests need to be run or diagnosed.
tools: ["execute", "read", "search"]
models: ["gpt-5.6-luna", "gpt-5.4-mini"]
reasoningEffort: low
include-custom-instructions: true
---
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |