In a nutshell
A Custom Agent is a specialist profile that hands Copilot a role, tools, and behavior all at once.
Even with the "same AI", you can switch between personas like Planner, Reviewer, and Tester — each with its own permissions.
What does it lock in?
A Custom Agent locks in not just a prompt, but the entire “working style” of an agent.
| Element | What does it define? | Example |
|---|---|---|
| Identity | What persona to adopt | Planner, Security Reviewer, Test Specialist |
| Description | When to invoke it | ”When creating a plan before implementation” |
| Tools | Which tools to use | read, search, edit, agent, github/* |
| Agents | Which subagents it can delegate to (requires agent in tools) | Research, Reviewer, * |
| Model | Which model to run on | Strong model for design, fast model for exploration |
| Target | Which runtime to target | github-copilot, vscode |
| MCP | Dedicated external tools | Jira, Figma, Playwright, internal API |
| Prompt | Decision criteria & output format | Success criteria, restrictions, review focus |
Four scopes
The same .agent.md can be published at four levels. The wider the reach, the more governance it needs.
| 🏢 Enterprise | 🏛️ Organization | 👥 Repository | 👤 Personal | |
|---|---|---|---|---|
| 📁 Location | Designated org’s .github-private → /agents/ | Org’s .github or .github-private → /agents/ | .github/agents/ | ~/.copilot/agents/ |
| 🎯 Scope | Every repository in the enterprise | Every member of the organization | That repository / workspace | All your workspaces |
| 🤝 Managed by | Enterprise owners / AI managers | Organization owners | The repo’s team, via Git | You only |
| 💡 Use case | Company-wide standards & compliance | Division-standard Planner / Reviewer | Project-specific Tester / Reviewer | Personal work style & preferences |
🆕 Organization and enterprise scopes are in public preview. Members receive the agents even without access to the source repository itself. 🛡️ Enterprise owners can protect agent files with a ruleset — but scope it to the designated organization, otherwise it also blocks org owners from editing organization-level agents.
Inside .agent.md
A Custom Agent is a Markdown file. The YAML frontmatter at the top is configuration; the body below is the instruction to the agent. For all configurable fields, see the Custom agents configuration reference.
---
name: design-reviewer
description: Review UI differences between Figma and implementation
target: github-copilot
model: Claude Sonnet 4.5
tools:
- read
- search
- github/pull-request-read
- figma/*
mcp-servers:
figma:
type: local
command: npx
args: ["-y", "figma-mcp-server"]
---
# Role
You are a design reviewer for UI implementations.
Compare Figma specifications against Pull Request diffs and review only visual differences: appearance, spacing, colors, and state variations.
# Rules
- Do not edit code
- Separate blocking vs. non-blocking findings
- Always include reproduction steps and screen widths to check
- Only flag issues grounded in Figma or the diff — no guessesA good Custom Agent is defined not by “who” it is, but by which decisions to delegate to it.
Agents vs. internal subagents
VS Code exposes Agent, Plan, and Ask to users. Internal helpers such as searchSubagent are tools invoked by another agent, not selectable .agent.md profiles.
| Surface | Agent / tool | What does it do? |
|---|---|---|
| Copilot Chat / VS Code | Agent | Implements complex tasks with editing and tool access |
| Copilot Chat / VS Code | Ask | Answers questions and researches without making changes |
| Copilot Chat / VS Code | Plan | Researches and outlines multi-step plans |
| VS Code internal | searchSubagent | Runs isolated, parallel codebase research and returns a summary |
🔑 VS Code’s former Explore behavior now appears through
searchSubagent. Its prompt and tool are implemented in TypeScript/TSX, so there is no editable Explore.agent.md.
Copilot CLI built-in subagents
| Agent | Best for |
|---|---|
| Explore | Fast, read-only codebase research |
| Task | Running tests, builds, and verbose commands |
| General-purpose | Complex multi-step work with the full toolset |
| Rubber-duck | Independently reviews plans and implementations. Assign it a different model with /subagents to test work from a perspective other than the model that created it |
| Code-review | High-confidence review of a diff |
| Research | Thorough GitHub and web research with citations |
| Security-review | High-confidence vulnerability review |
🦆 Rubber-duck’s strength is cross-model review. Instead of asking a model to evaluate its own work, use another model to critique the plan or implementation and expose blind spots or reasoning biases.
What happens inside the harness?
When a user invokes a Custom Agent, the harness fetches its .agent.md, narrows the available tools, injects the agent definition, and appends the prompt. The model ends up with a four-layer context: SYSTEM & TOOLS / INSTRUCTIONS / CUSTOM AGENT / PROMPT.
💡 INSTRUCTIONS is already there for every run. A Custom Agent only adds the three layers above it: tool narrowing, agent definition, and prompt.
Subagents — offloading task-specific context
When you need a deep dive, have the harness spin up a subagent. It does the heavy reading in its own context window and returns only a summary to the main session.
Use the Right LLM for Each Job with Custom Agents
AI models are trained on different data with different architectures. No single model is best at everything.
Only Copilot lets enterprises run Claude + Gemini + Codex + Microsoft in one governed, auditable platform.
What Is the Best Model? ❌
- “What is the best model?” ➡️ Wrong question
- “What is the best model for this job?” ➡️ Good question
| Dev Task | Best Model Cost/Performance (Example) |
|---|---|
| Writing Requirements | Claude Opus 4.8 |
| Architecture & Design | Gemini 3.1 Pro |
| Code Planning | Claude Opus 4.8 |
| Code Generation | Claude Sonnet 4.6 |
| Test Creation | Claude Sonnet 4.6 |
| Code Review | GPT-5.5 Codex |
| CI/CD & Automation | GPT-5.4 Codex |
| Documentation | Gemini 3.1 Pro |
| High Volume & Cost | MAI-Code-1-Flash |
Sources (benchmarks): SWE-bench Verified ↗ · Terminal-Bench ↗ · Aider Polyglot ↗ · LMArena ↗. Models are examples only and vary by task and preference.