Custom agent file reference

This article describes custom agent file syntax, frontmatter fields, and harness-specific configuration in VS Code. For creation steps, file locations, and a complete starter example, see Create and manage custom agents.

File structure

A custom agent file contains an optional YAML header, enclosed by --- delimiters, followed by a Markdown body with the agent's instructions:

---
name: Reviewer
description: Review changes without editing files
tools: ['read', 'search']
---
Review the supplied changes for correctness and missing tests.
Report actionable findings with file references. Do not edit files.

The fields below describe the VS Code format. Files in .claude/agents use the Claude agent format.

Harness compatibility

The selected agent harness determines which fields and tool names take effect. A shared file location does not imply identical behavior across harnesses.

• Local supports the VS Code tool names, subagent configuration, handoffs, and agent-scoped hooks described below.
• Copilot supports custom agent configuration through its runtime. Use the field-specific guidance below and the Copilot custom agent documentation. Local handoffs do not apply. See Copilot-specific configuration for fields recognized by the editor but not forwarded during agent conversion.
• Claude uses its own agent format and runtime behavior.
• Copilot cloud agent has a separate configuration reference.

By default, the selected harness determines the editor's completions, hovers, and validation. Set target: github-copilot to interpret the file with the Copilot schema, or target: vscode to use the Local schema. The target field overrides file interpretation, not the harness that runs your session.

The editor identifies attributes that aren't supported by the effective target. For example, Local doesn't accept skills or mcp-servers, and Copilot doesn't accept handoffs, agents, argument-hint, or advancedOptions.

Header fields

Fields are optional unless noted. Defaults and harness-specific behavior are listed where applicable.

Tools

In Copilot, tools supports the built-in aliases execute, read, edit, search, agent, web, and todo. Use * to select all tools.

Use completions to select available client-provided tools with their canonical qualified references, such as browser/<tool>, notebook/<tool>, and vscode/<tool>. Extension tools retain <extensionId>/<tool> references. Don't strip these prefixes or replace them with internal runtime registration names.

To include all tools published by a configured MCP server, use <server name>/*. A namespace's availability depends on the session's MCP inventory. Review tool availability before reusing a tool list in another harness.

In Local, tools can include built-in tools, MCP tools, and tools contributed by extensions. Existing user-defined tool-set references are deprecated and are not supported in Copilot. See Replace tool sets. Built-in aliases such as read and search are separate from user-defined tool-set files.

For example, a Local agent can combine built-in tools with an MCP server namespace:

tools: ['read', 'search', '<server name>/*']

Replace <server name> with the name of a configured MCP server. If tools is omitted in Local, the tools enabled in the tools picker are available. Unavailable tools are ignored.

Local's agent/runSubagent reference isn't a portable delegation tool name. Copilot uses its native task tool for delegation. A qualified client-tool reference such as vscode/toolSearch is valid only when that tool is provided to the Copilot session; the prefix alone doesn't make it Local-only. Review both the tool list and instructions that require a particular tool. For compatibility checks and known editing limitations, see the tool-discovery migration FAQ.

Model preferences

Use the model identifiers inserted by completions for the intended harness. Copilot completions insert runtime model IDs, including exact provider-qualified IDs for BYOK models. These differ from Local's qualified model display names.

To specify a prioritized list for Copilot, replace the placeholders with available model IDs. Keep the array in your preferred order:

model: ['<preferred model ID>', '<fallback model ID>']

The Copilot editor schema also recognizes model-policy: preferred and model-policy: required. Conversion of plugin-provided agents selects a model from the authored list but doesn't forward model-policy. Don't rely on required to enforce a required-model policy for those converted agents.

Skills

In Copilot, use skills to name skills to load into the custom agent's context:

skills: ['<skill name>']

Replace <skill name> with an enabled skill available to the intended Copilot harness. Completions and hovers show descriptions, sources, and availability details where provided. Disabled or temporarily unavailable skills can also appear, so review their status before selecting them.

This inventory validation is specific to Copilot files. Setting target: vscode uses Local interpretation instead. For skill creation and supported locations, see Agent skills.

Copilot-specific configuration

The editor provides nested completions, hovers, and structural validation for these Copilot fields:

• github: a toolsets array and a permissions map. GitHub MCP toolsets aren't Local user-defined tool-set files.
• mcp-servers: a map of server definitions, with local command-based or remote URL-based configurations. The editor checks property types, tool arrays, URLs, and positive timeouts.
• hooks: event maps with action arrays. Validation checks event-specific action combinations, matcher patterns, URLs, and positive timeouts. Use the agent-scoped hook reference for runtime requirements.

Structural validation doesn't start or authenticate MCP servers, or prove that a hook executes.

Subagent configuration

In Local, restrict a coordinator to named workers by combining agents with the agent tool set:

tools: ['agent']
agents: ['Researcher', 'Implementer']

Agent names are case-sensitive. Explicitly listing an agent in agents permits invocation even if that worker sets disable-model-invocation: true. To allow a subagent to delegate further, enable chat.subagents.allowInvocationsFromSubagents Open in VS Code Open in VS Code Insiders . This also applies to an agent that lists itself. See Nested subagents.

For complete coordinator and worker files, see Delegate implementation to a worker.

Visibility and invocation

To hide an agent from the picker while keeping it available for delegation:

user-invocable: false
disable-model-invocation: false

These fields change the shared agent definition, not a personal visibility preference. See Customize the agents dropdown list.

Handoff fields

Each object in the handoffs array defines a transition in the Local harness:

handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
    model: <model name> (copilot)

Replace the model placeholder with an available model, or omit model. For a planning-to-implementation walkthrough, see Handoffs.

Body

The Markdown body contains the instructions the agent follows, such as its task, guidelines, and expected output.

When you select the custom agent in the Chat view, its body instructions are added after your custom instructions and take precedence if they conflict.

Local file and tool references

In Local, reference files with Markdown links or #file: syntax. Relative paths resolve from the custom agent file. Use ~ or ~/ to reference your home folder, and use Unix-style / separators to keep paths portable across operating systems.

Follow the [review checklist](./review-checklist.md).
Use #file:~/copilot/security-guidelines.md for security reviews.

In Local, reference a tool with #tool:<tool-name>, such as #tool:web/fetch.

Copilot body placeholders

Copilot file editing recognizes these case-sensitive placeholders:

The editor provides completions, hovers, and highlighting for recognized placeholders and identifies unknown placeholder-like values. Local #file: and #tool: references are identified as unsupported for Copilot. Use ordinary Markdown links for file references and the tools frontmatter field to configure tools instead.

Tool list priority

In Local, a prompt file's tools list takes precedence over the custom agent's tools list. Other harnesses don't load prompt files. For the full order, see Tool list priority.

Claude agent format

Agent files in .claude/agents use plain .md files and the Claude subagents format.

The Claude harness implements these fields according to its provider documentation. When Local loads a Claude-format agent, it maps supported Claude tool and model names to their VS Code equivalents. This compatibility does not make all Claude runtime features available in Local.

Related resources

• Create and manage custom agents
• Use subagents
• Configure agent hooks
• Compare agent harnesses