Skip to main content

​
Using Custom Agents

Custom agents allow you to “specialize” GitHub Copilot through simple file-based configuration. Each agent is a .agent.md file that defines a specific AI persona or specialized mode for particular workflows and tools.

​
What are Custom Agents?

Custom agents are specialized GitHub Copilot agents that integrate with MCP (Model Context Protocol) servers to provide enhanced capabilities for specific workflows. They can be used in:
  • Copilot Coding Agent (CCA) - Assign to issues for automated development
  • VS Code - Activate in chat sessions alongside built-in agents
  • Copilot CLI - Coming soon
Custom agents differ from instructions and skills:
  • Agents define AI personas with specific tools and behaviors
  • Instructions provide coding standards that apply to file patterns
  • Skills are self-contained capabilities with bundled resources

​
Installing Custom Agents

There are multiple ways to install custom agents:
Browse the Agents Catalog and click the install button:
  • VS Code: Click the VS Code install badge
  • VS Code Insiders: Click the VS Code Insiders install badge
The agent file will be automatically downloaded to your workspace.

​
Agent File Structure

Every agent file follows this structure: 
---
description: 'Brief description of what the agent does'
name: 'Human-Readable Agent Name'
tools: ['tool1', 'tool2', 'tool3']
model: 'claude-sonnet-4.5'  # Strongly recommended
---

# Agent Instructions

Detailed instructions for how the agent should behave...
  • description (required): Wrapped in single quotes, describes the agent’s purpose
  • name (required): Human-readable name (e.g., “Debug Mode” not “debug-mode”)
  • tools (recommended): Array of tool names the agent can use
  • model (strongly recommended): Specific AI model to use
  • File naming: Use lowercase with hyphens (e.g., debug-mode.agent.md)

​
Activating Agents

Once installed, agents can be activated in different environments:
  1. Open the GitHub Copilot chat panel
  2. Type @ to see available agents
  3. Select your custom agent from the list
  4. Start chatting with the specialized agent
Example:
@debug-mode Find and fix the null reference error

​
MCP Server Integration

Many custom agents require MCP servers to function:
1

Check Agent Requirements

Review the agent’s documentation to see which MCP servers it needs. For example, the Context7 agent requires the Context7 MCP server.
2

Install Required MCP Servers

Click the MCP server install badges in the agent documentation, or manually configure in your VS Code settings:
{
  "github.copilot.chat.mcp.servers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "your-api-key-here"
      }
    }
  }
}
3

Verify Access

The agent will have access to tools from configured MCP servers. Check the agent’s tools field to see what capabilities it expects.
Here are some commonly used agents from the repository: 
---
description: 'Debug your application to find and fix a bug'
name: 'Debug Mode Instructions'
tools: ['edit/editFiles', 'search', 'execute/runInTerminal']
---

# Debug Mode
Systematically identify, analyze, and resolve bugs...

​
Creating Your Own Agents

Want to create custom agents for your team? See the Custom Agent File Guidelines in the repository. Key requirements:
  • Use .agent.md file extension
  • Include required frontmatter fields
  • Follow lowercase-with-hyphens naming convention
  • Specify the model field for consistent behavior
  • List tools the agent needs

​
Best Practices

  • Use specialized agents for domain-specific tasks (e.g., security, performance)
  • Use general agents for everyday coding
  • Switch agents based on the current task context
  • Combine agents with instructions for maximum effectiveness
  • Store agents in .github/copilot/ for repository-wide availability
  • Name agents clearly to indicate their purpose
  • Document agent requirements (MCP servers, environment variables)
  • Share successful agents with your team via pull requests
Agent not appearing:
  • Check the file is in .github/copilot/
  • Verify frontmatter is valid YAML
  • Reload VS Code window
Agent not working as expected:
  • Verify required MCP servers are configured
  • Check the tools field matches available capabilities
  • Review agent instructions for clarity

Build docs developers (and LLMs) love

Get started for freeTalk to us