Custom agents are specialized assistants that give GitHub Copilot a focused persona, specific tool access, and domain expertise. Unlike instructions (which apply passively) or skills (which handle individual tasks), agents define a complete working style—they shape how Copilot thinks, what tools it reaches for, and how it communicates throughout an entire session.
This article shows you how to design, structure, and deploy effective agents for your team’s workflows.
Custom agents are Markdown files (*.agent.md) that configure GitHub Copilot with:
A persona: The expertise, tone, and working style the agent adopts
Tool access: Which built-in tools and MCP servers the agent can use
Guardrails: Boundaries and conventions the agent follows
A model preference: Which AI model powers the agent (optional but recommended)
When a user selects a custom agent in VS Code or assigns it to an issue via the Copilot coding agent, the agent’s configuration shapes the entire interaction.
Key Points:
Agents persist across a conversation—they maintain their persona and context
Agents can invoke tools, run commands, search codebases, and interact with MCP servers
Multiple agents can coexist in a repository, each serving different workflows
Agents are stored in .github/agents/ and are shared with the entire team
description: 'Expert security auditor that reviews code for OWASP vulnerabilities, authentication flaws, and supply chain risks'
model: Claude Sonnet 4
tools: ['codebase', 'terminal', 'github']
---
name (recommended): A human-readable display name for the agent.
description (required): A clear summary of what the agent does. This is shown in the agent picker and helps users find the right agent.
model (recommended): The AI model that powers the agent. Choose based on the complexity of the task—use more capable models for nuanced reasoning.
Model fallback lists (v1.0.83+): model can list several models, tried in order until one is available to you — useful if your preferred model is temporarily rate-limited or not enrolled for your account. Pair it with model-policy: required to keep the agent restricted to that list even if the user tries to switch models mid-session:
---
name: 'Security Reviewer'
model: [Claude Sonnet 4.5, Claude Sonnet 4, GPT-5]
model-policy: required
tools: ['codebase', 'terminal', 'github']
---
reasoningEffort(v1.0.66+): Override the reasoning effort level for this agent. Accepted values are low, medium, and high. This lets you pin specific agents to a cost/quality tradeoff regardless of the user’s global setting — for example, a quick code-formatting agent can use low effort, while a security reviewer uses high:
---
name: 'Security Reviewer'
description: 'Thorough security audit for OWASP vulnerabilities'
model: Claude Sonnet 4
reasoningEffort: high
tools: ['codebase', 'terminal', 'github']
---
tools (recommended): An array of built-in tools and MCP servers the agent can access. Common tools include:
Tool
Purpose
codebase
Search and analyze code across the repository
terminal
Run shell commands
github
Interact with GitHub APIs (issues, PRs, etc.)
fetch
Make HTTP requests to external APIs
edit
Modify files in the workspace
For MCP server tools, reference them by server name (e.g., postgres, docker). See Understanding MCP Servers for details.
Built-in /security-review: Before creating a custom security-reviewer agent, note that GitHub Copilot CLI includes a built-in /security-review command (available to all users since v1.0.64). It performs a security-focused analysis of staged changes or specified files. Custom security-reviewer agents are still valuable for domain-specific rules, team conventions, and deep integration with MCP tools like Sentry or SAST platforms.
---
name: 'Accessibility Auditor'
description: 'Reviews UI components for WCAG 2.1 AA compliance and accessibility best practices'
model: Claude Sonnet 4
tools: ['codebase']
---
You are an accessibility expert who reviews UI components for WCAG compliance.
## Audit Areas
- Semantic HTML structure
- ARIA attributes and roles
- Keyboard navigation support
- Color contrast ratios (minimum 4.5:1 for text)
- Screen reader compatibility
- Focus management in dynamic content
## When Reviewing
- Check every interactive element has an accessible name
- Verify form inputs have associated labels
- Ensure images have meaningful alt text (or empty alt for decorative)
- Test that all functionality is keyboard-accessible
Agents become significantly more powerful when connected to external tools via MCP servers. Reference MCP tools in the tools array:
---
name: 'Database Administrator'
description: 'Expert DBA for PostgreSQL performance tuning, query optimization, and schema design'
tools: ['codebase', 'terminal', 'postgres-mcp']
---
The agent can then query your database, analyze query plans, and suggest optimizations—all within the conversation. For setup details, see Understanding MCP Servers.
Keep agents focused—one persona per file. If you find an agent trying to do too many things, split it into multiple agents or extract common tasks into skills that agents can invoke.
A: In VS Code, open Copilot Chat and use the agent picker dropdown at the top of the chat panel. Your custom agents appear alongside built-in options. You can also @mention an agent by name.
In Copilot CLI, custom agents are discoverable via the agent picker inside a session. Clients that integrate with Copilot CLI using the Agent Coordination Protocol (ACP) can also list available custom agents and switch between them programmatically via the agent session configuration option (v1.0.40+). This allows tools like Zed, Neovim plugins, and CI pipelines driving Copilot via ACP to surface the agent picker and switch agents without requiring a slash command. ACP clients also receive the agent’s live plan as it works through multi-step tasks (v1.0.40+), so they can display real-time progress to their users without waiting for each turn to complete.
Q: Can agents use skills?
A: Yes. Agents can discover and invoke skills during a conversation based on the user’s intent. Skills extend what an agent can do without bloating the agent’s own instructions.
Q: How many agents should a repository have?
A: Start with 2–3 agents for your most common workflows. Add more as patterns emerge. Typical teams have 3–8 agents covering areas like code review, infrastructure, testing, and documentation.
Q: Can I use an agent with the Copilot coding agent?
A: Yes. When you assign an issue to Copilot, you can specify which agent should handle it. The agent’s persona and tool access apply to the autonomous coding session. See Using the Copilot Coding Agent for details.
Q: Should agents include code examples?
A: Yes, when defining output format or coding patterns. Show what you expect the agent to produce—review formats, code structure, commit message style, etc.
❌ Too broad: “You are a software engineer” — no focus or guardrails
✅ Instead: Define specific expertise, review criteria, and output format
❌ No tools specified: Agent can’t search code or run commands
✅ Instead: Declare the tools the agent needs in frontmatter
❌ Conflicting with instructions: Agent says “use tabs” but instructions say “use spaces”
✅ Instead: Agents should complement instructions, not contradict them
❌ Monolithic agent: One agent that handles security, testing, docs, and deployment
✅ Instead: Create focused agents and let them invoke shared skills