Custom Agent — Playbook

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`)	`Explore`, `*`
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

Two scopes

	👥 Team shared	👤 Personal
📁 Location	`.github/agents/*.agent.md`	`~/.copilot/agents/`
🎯 Scope	That repository / workspace	All your workspaces
🤝 Sharing	Managed in Git, shared with team	Local only
💡 Use case	Team-standard Planner / Reviewer / Tester	Personal work style & preferences

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 guesses

A good Custom Agent is defined not by “who” it is, but by which decisions to delegate to it.

Built-in agent examples

Copilot Chat and CLI come with purpose-built agents out of the box.
Custom Agents are the mechanism for extending this to your own team.

Surface	Agent	What does it do?
Copilot Chat / VS Code	Ask	Answers questions without making changes
Copilot Chat / VS Code	Explore	Fast read-only codebase exploration and Q&A subagent
Copilot Chat / VS Code	Plan	Researches and outlines multi-step plans
Copilot CLI	Explore	Quick codebase analysis. Ask questions about the code without adding to the main context
Copilot CLI	Task	Runs commands such as tests and builds, returning a brief summary on success and full output on failure
Copilot CLI	General-purpose	Handles complex multi-step tasks requiring the full toolset and high-quality reasoning in a separate context
Copilot CLI	Rubber-duck	Gives high-signal feedback on plans and implementations, catching bugs, logic errors, and design flaws (never edits code)
Copilot CLI	Code-review	Reviews changes and surfaces only genuinely important issues with low noise
Copilot CLI	Research	A subagent that runs thorough searches: digs through GitHub repos, fetches files, and reports findings with citations
Copilot CLI	Security-review	Reviews changes for high-confidence security vulnerabilities (11 categories) with severity and confidence scores

Display names may appear shortened depending on the UI preview, but the official CLI names are General-purpose and Code-review. For how to create custom agents in the CLI, see About Copilot CLI custom agents and Create custom agents for CLI.

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.

📚 Different Training Data

Models trained on different corpora have different knowledge gaps and strengths.

⚙️ Different Architectures

Reasoning vs speed vs context window; each model excels at different task types.

✅ Cross-Validation

Running multiple models on the same task catches bugs one model alone would miss.

🎯 Cost Optimization

The right model per task won't just be about quality, it'll be about budget.

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

● Anthropic ● OpenAI ● Google ● Microsoft

Sources (benchmarks): SWE-bench Verified ↗ · Terminal-Bench ↗ · Aider Polyglot ↗ · LMArena ↗. Models are examples only and vary by task and preference.