Skip to main content

​
What are Custom Agents?

Custom agents are specialized GitHub Copilot configurations that enhance the coding agent’s capabilities for specific tasks, domains, or workflows. They allow you to “teach” Copilot new skills by providing structured instructions, tools, and context through simple markdown files.

Browse the Agent Catalog

Explore hundreds of ready-to-use agents for different languages, frameworks, and use cases.

​
How Agents Work

Agents are defined using .agent.md files with YAML frontmatter that specifies:
  • Instructions: Natural language guidance for how Copilot should behave
  • Tools: Which capabilities the agent has access to
  • MCP Servers: External services the agent can connect to
  • Model: Specific AI model to use (e.g., GPT-4, Claude)

​
Agent File Structure

All agents follow the .agent.md format with YAML frontmatter: 
---
name: 'API Architect'
description: 'Your role is that of an API architect. Help mentor the engineer by providing guidance, support, and working code.'
tools: ['codebase', 'edit/editFiles', 'search', 'runCommands']
model: 'gpt-4'
---

# API Architect mode instructions

Your primary goal is to act on the mandatory and optional API aspects...

​
Frontmatter Fields

​
name
string
required
Human-readable name for the agent (e.g., “API Architect” not “api-architect”)
​
description
string
required
Brief description of what the agent does. Must be wrapped in single quotes.
​
tools
array
List of tools the agent can access. Examples: codebase, edit/editFiles, search, runCommands, web/fetch
​
model
string
Specific AI model to use. Strongly recommended to specify. Examples: gpt-4, claude-3-5-sonnet
​
mcp-servers
object
MCP (Model Context Protocol) server configurations for external integrations

​
MCP Server Integration

Many agents integrate with MCP servers to access external services and APIs. MCP servers enable agents to:
  • Query external databases and APIs
  • Access real-time documentation
  • Interact with cloud services
  • Retrieve up-to-date library information

​
MCP Server Configuration

Agents define MCP servers in their frontmatter: 
mcp-servers:
  context7:
    type: http
    url: "https://mcp.context7.com/mcp"
    headers:
      CONTEXT7_API_KEY: "${{ secrets.COPILOT_MCP_CONTEXT7 }}"
    tools:
      - "get-library-docs"
      - "resolve-library-id"

​
Real-World MCP Examples

Context7

Provides up-to-date library documentation and best practices

Apify

Access web scraping actors and automation workflows

CAST Imaging

Software discovery and impact analysis tools

Comet Opik

LLM observability, prompt management, and tracing

​
Installing Agents

The easiest way to install agents is using the VS Code install buttons:
  1. Browse the Agent Catalog
  2. Click the Install in VS Code button for your desired agent
  3. The agent will be automatically added to your repository
Install buttons are available for both VS Code and VS Code Insiders.

​
Manual Installation

You can also manually download .agent.md files:
  1. Download the agent file from the repository
  2. Place it in your project’s .github/copilot/ directory
  3. Restart GitHub Copilot to load the new agent
# Download an agent
curl -O https://raw.githubusercontent.com/github/awesome-copilot/main/agents/api-architect.agent.md

# Move to Copilot directory
mkdir -p .github/copilot
mv api-architect.agent.md .github/copilot/

​
Using Agents

Once installed, agents can be used in multiple ways:

​
In VS Code Chat

Access agents through the chat interface: 
@agent-name your question or task

​
In Copilot Edits

Assign an agent to guide multi-file edits:
  1. Open Copilot Edits panel
  2. Select your agent from the dropdown
  3. Describe your changes

​
Via Copilot CLI

Use agents from the command line (coming soon): 
gh copilot agent run api-architect "design a REST API for user management"

​
Agent Categories

Agents are organized by their primary use case:
Agents specialized for specific programming languages:
  • C# Expert: .NET development and modernization
  • C++ Expert: Modern C++ best practices
  • Clojure Interactive Programming: REPL-first development
  • Go MCP Development: Building MCP servers in Go
  • Java MCP Development: MCP server creation in Java
Agents for cloud platforms and infrastructure:
  • Azure Principal Architect: Well-Architected Framework guidance
  • Azure SaaS Architect: Multi-tenant application design
  • Bicep Specialist: Azure infrastructure as code
  • Terraform Azure: Azure Terraform implementation
  • ARM Migration: x86 to ARM cloud migration
Agents for CI/CD and automation:
  • DevOps Expert: Infinity loop principle workflows
  • GitHub Actions: Workflow automation
  • Docker Expert: Container optimization
  • Kubernetes: Orchestration and deployment
Agents for frontend and web applications:
  • React Expert: Modern React patterns
  • Next.js: App router and server components
  • Tailwind CSS: Utility-first styling
  • Accessibility Expert: WCAG compliance
  • AEM Frontend: Adobe Experience Manager
Agents for software architecture:
  • API Architect: REST API design and mentoring
  • ADR Generator: Architectural decision records
  • Blueprint Mode: Structured problem-solving
  • Context Architect: Multi-file change planning
Agents focused on code quality:
  • Test Expert: Test-driven development
  • Code Review: Best practice reviews
  • Security Auditor: Security vulnerability scanning
  • Performance Optimizer: Code optimization
Agents for third-party integrations:
  • Apify Integration: Web scraping automation
  • Context7 Expert: Latest library documentation
  • CAST Imaging: Impact analysis
  • Dynatrace Expert: Observability integration

​
Creating Your Own Agents

Want to create custom agents for your team?
1

Create the file

Create a new .agent.md file with YAML frontmatter
2

Define metadata

Add name, description, and optional tools and model fields
3

Write instructions

Use natural language to describe how the agent should behave
4

Test thoroughly

Try your agent with various scenarios to ensure it works as expected
5

Share (optional)

Contribute back to the community via pull request

Contributing Guide

Learn how to contribute your agents to the Awesome GitHub Copilot repository

​
Best Practices

  • Use clear, concise natural language
  • Provide concrete examples of expected behavior
  • Define scope and boundaries clearly
  • Include common patterns and anti-patterns
  • Reference specific tools and their usage
  • Only request tools the agent truly needs
  • Understand tool capabilities and limitations
  • Document why specific tools are required
  • Test agent behavior with and without tools
  • Specify model for consistent behavior
  • Choose models based on task complexity
  • Consider token limits and costs
  • Test with your target model during development
  • Use descriptive, human-readable names
  • Keep file names lowercase with hyphens
  • Name field should match agent purpose
  • Description should be concise but informative

​
Next Steps

Browse Agent Catalog

Explore hundreds of ready-to-use agents

Learn About Instructions

Discover coding standards and patterns

Explore Skills

Self-contained task bundles with resources

View Plugins

Pre-packaged collections of related agents

Build docs developers (and LLMs) love

Get started for freeTalk to us