This reference article provides detailed configuration information for custom agents. For general information about creating custom agents, seeCreating custom agents for Copilot coding agent.

YAML frontmatter properties

The following table outlines the properties that are supported in repository-level agent profiles, organization or enterprise level agent profiles, and in VS Code. The configuration file's name (minus.md or.agent.md) is used for deduplication between levels so that the lowest level configuration takes precedence.

Define the agent's behavior, expertise, and instructions in the Markdown content below the YAML frontmatter. The prompt can be a maximum of 30,000 characters.

Tools

The custom agenttools property controls which tools are available to your agent, including those from MCP servers.

While you cannot configure MCP servers directly within an agent profile for repository-level custom agents, your custom agent will have access to MCP server tools that have been configured in the repository settings. For more information on configuring MCP servers for coding agent in a repository, seeExtending GitHub Copilot coding agent with the Model Context Protocol (MCP).

You can configuretools using the following approaches:

• Enable all available tools: Omit thetools property entirely or usetools: ["*"] to enable all available tools. This will include all MCP server tools configured in the repository settings.
• Enable specific tools: Provide a list of specific tool names or aliases (for example,tools: ["read", "edit", "search"]) to enable only those tools. For available tool aliases, seeTool aliases below.
  • Note that if your repository has MCP servers configured, you can choose to make only specific tools from those servers available to your custom agent. Tool names from specific MCP servers can be prefixed with the server name followed by a/. For example,some-mcp-server/some-tool.
  • You can also explicitly enable all tools from a specific MCP server usingsome-mcp-server/*.
  • Tools from VS Code extensions can use the extension name as a proxy, likeazure.some-extension/some-tool.
• Disable all tools: Use an empty list (tools: []) to disable all tools for the agent.

All unrecognized tool names are ignored, which allows product-specific tools to be specified in an agent profile without causing problems.

Tool aliases

The following tool aliases are available for custom agents. All aliases are case insensitive:

Tool names for "out-of-the-box" MCP servers

The following MCP servers are available out-of-box for Copilot coding agent and can be referenced using namespacing:

MCP server configuration details

The following sample agent profile shows an organization-level agent with MCP server and secret configured. Additionally, only one tool from the MCP server has been enabled in thetools property in the YAML frontmatter:

---name: my-custom-agent-with-mcpdescription: Custom agent descriptiontools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']mcp-servers:  custom-mcp:    type: 'local'    command: 'some-command'    args: ['--arg1', '--arg2']    tools: ["*"]    env:      ENV_VAR_NAME: $---Prompt with suggestions for behavior and output

Themcp-servers property in an agent profile is a YAML representation of the JSON configuration format used to configure MCP servers for Copilot coding agent.

Most sub-properties are the same as the JSON representation. The following sections describe changes from the initial implementation of MCP configuration in Copilot coding agent that are relevant to custom agents. For more information about the JSON configuration format, seeExtending GitHub Copilot coding agent with the Model Context Protocol (MCP).

MCP server type

For compatibility, thestdio type used by Claude Code and VS Code is mapped to coding agent'slocal type.

MCP server environment variables and secrets

Custom agent MCP configuration supports the same environment variable and secret replacement capabilities as existing repository-level MCP configurations. Similar to repository-level configurations, secrets and variables can be sourced from the "copilot" environment in the repository's settings. The syntax for referencing these values has been expanded to support common patterns used in GitHub Actions and Claude Code.

Both the repository-level MCP JSON configuration and the custom agent YAML configuration support the following syntax patterns:

• COPILOT_MCP_ENV_VAR_VALUE - Environment variable only (not recommended due to header differences)
• $COPILOT_MCP_ENV_VAR_VALUE - Environment variable and header
• ${COPILOT_MCP_ENV_VAR_VALUE} - Environment variable and header (Claude Code syntax)

The custom agent YAML configuration supports the following additional syntax patterns:

• ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }} - Environment variable and header
• ${{ var.COPILOT_MCP_ENV_VAR_VALUE }} - Environment variable and header

Example agent profile configurations

The following examples demonstrate what an agent profile could look like for the common tasks of writing tests or planning the implementation of a project. For additional inspiration, see theCustom agents examples in the customization library. You can also find more specific examples in theawesome-copilot community collection.

Testing specialist

This example enables all tools by omitting thetools property.

---name: test-specialistdescription: Focuses on test coverage, quality, and testing best practices without modifying production code---You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:- Analyze existing tests and identify coverage gaps- Write unit tests, integration tests, and end-to-end tests following best practices- Review test quality and suggest improvements for maintainability- Ensure tests are isolated, deterministic, and well-documented- Focus only on test files and avoid modifying production code unless specifically requestedAlways include clear test descriptions and use appropriate testing patterns for the language and framework.

---name: test-specialistdescription: Focuses on test coverage, quality, and testing best practices without modifying production code---You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:- Analyze existing tests and identify coverage gaps- Write unit tests, integration tests, and end-to-end tests following best practices- Review test quality and suggest improvements for maintainability- Ensure tests are isolated, deterministic, and well-documented- Focus only on test files and avoid modifying production code unless specifically requestedAlways include clear test descriptions and use appropriate testing patterns for the language and framework.

Implementation planner

This example only enables a subset of tools.

---name: implementation-plannerdescription: Creates detailed implementation plans and technical specifications in markdown formattools: ["read", "search", "edit"]---You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:- Analyze requirements and break them down into actionable tasks- Create detailed technical specifications and architecture documentation- Generate implementation plans with clear steps, dependencies, and timelines- Document API designs, data models, and system interactions- Create markdown files with structured plans that development teams can followAlways structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

---name: implementation-plannerdescription: Creates detailed implementation plans and technical specifications in markdown formattools: ["read", "search", "edit"]---You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:- Analyze requirements and break them down into actionable tasks- Create detailed technical specifications and architecture documentation- Generate implementation plans with clear steps, dependencies, and timelines- Document API designs, data models, and system interactions- Create markdown files with structured plans that development teams can followAlways structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

Processing of custom agents

Custom agents names

In the case of naming conflicts, the lowest level configuration overrides higher-level configurations. This means that a repository-level agent would take precedence over an organization-level agent, and the organization-level agent would override an enterprise-level agent.

Versioning

Custom agent versioning is based on Git commit SHAs for the agent profile file. This allows you to create branches or tags with different versions of custom agents as needed. When you assign a custom agent to a task, the custom agent will be instantiated using the latest version of the agent profile for that repository and branch. When the agent creates a pull request, interactions within the pull request use the same version of the custom agent for consistency.

Tools processing

Thetools list filters the set of tools that are made available to the agent - whether built-in or sourced from MCP servers. When you configure tools in your agent profile, the behavior depends on what you specify:

• If no tools are specified, all available tools are enabled
• An empty tools list (tools: []) disables all tools
• A specific list (tools: [...]) enables only those tools

MCP server configurations

For MCP server configurations, there is a specific processing order that ensures proper override behavior: out-of-the-box MCP configurations (like the GitHub MCP) are processed first, followed by the custom agent MCP configuration (supported for organization or enterprise level custom agents only), and finally repository-level MCP configurations. This allows each level to override settings from the previous level as appropriate.