💡 Templates & Examples: Looking for ready-to-use agent templates? Check out the gh-copilot-templates repository:

• Generalized templates to copy and customize
• Personalized examples showing specialized agents in action

VSCode Agents 1.4: Agent Files

Instruction files give Copilot your conventions. Prompt files give you reusable commands. Agent files give you specialized personas.

An agent file (.agent.md) is a configured instance of a Copilot agent with a specific role, limited tools, and tailored instructions. The default Copilot agent is a generalist. Custom agents are specialists: a planner that only reads and researches, a tester that only writes tests, a reviewer that critiques without editing.

The power comes from constraint. By limiting what an agent can do, you make it better at what it should do.

Why Custom Agents Matter

Different tasks need different capabilities. A planner shouldn't edit code. An implementer needs write access. A reviewer should critique without making changes.

Without custom agents, you're constantly specifying constraints in prompts: "Don't edit, just review." That's friction. Agent files encode constraints once, then you switch agents like switching tools.

The other benefit is handoffs. You can design workflows where one agent completes its task, then passes context to the next agent. Plan → Implement → Review, each step handled by a specialist.

But the real reason custom agents matter is subagents. When the main agent delegates work via runSubAgent, the subagent is context-isolated. It doesn't inherit your chat history, conventions, or instructions. Without custom agents, subagents run with default settings: no knowledge of your codebase, access to all tools, no constraints. It's random whether they follow your patterns.

With custom agents, you define exactly what runSubAgent calls. Your main agent becomes an orchestrator that delegates to the right specialist, each with proper tools and instructions. This dramatically reduces deviation from expected results.

This is why agents feel like a team instead of one confused generalist. It's also why you should start new chats frequently: models suffer from context pollution. Fresh chats, specialized agents, and deliberate delegation.

Agent Files vs Everything Else

Quick clarification:

• AGENTS.md: Repo-wide conventions for all agents across tools (Cursor, Copilot, Windsurf). See Instruction Files.
• copilot-instructions.md: Repo-wide conventions specific to GitHub Copilot.
• .instructions.md: Path-specific conventions that auto-inject for matching files.
• .prompt.md: Reusable commands you invoke manually with /command. See Custom Prompts.
• .agent.md: Configured Copilot personas with specific tools, models, and instructions.

Agent files change who Copilot is, not just what it knows.

File Structure

Agent files are markdown with YAML frontmatter. See the planner template for a complete example.

Frontmatter Properties

Tool Restriction

The tools property is the key constraint:

• Read-only: ['search', 'read', 'web'] for research without edits
• Write: ['edit', 'execute'] for code modification
• Full: Omit tools entirely for all capabilities

Find available tools by clicking Configure Tools in the chat view (right of the model selector).

Designing Agents

Think of agents like developer roles. Instead of one generalist, imagine distinct hats:

• Researcher: Gathers context, reads docs, finds patterns. Tools: search, web, read
• Planner: Creates specs, breaks down tasks. Tools: search, read, todo
• Implementer: Writes code, follows specs. Tools: search, edit, read
• Tester: Writes tests, validates behavior. Tools: search, edit, read, execute
• Reviewer: Critiques code (read-only). Tools: search, read

See the templates for complete configurations.

Handoffs

Handoffs chain agents together. After an agent responds, handoff buttons appear to transition to the next agent with context.

Example workflow: Plan → Implement → Review

Each agent's handoffs property defines buttons. With send: false, the prompt pre-fills but doesn't auto-submit. Set send: true for automated transitions (use cautiously).

See the handoff examples for complete configurations with circular workflows.

Where to Store Agent Files

• Workspace: .github/agents/*.agent.md for team-shared, project-specific agents
• User profile: Personal agents you reuse across workspaces

To create one in VS Code:

1. Open Copilot Chat
2. Select "Configure Custom Agents..." from the agents dropdown
3. Click "Create new custom agent"
4. Choose "Workspace" or "User profile"

VS Code creates the file with autocomplete for frontmatter properties.

When NOT to Use Agent Files

Custom agents add complexity. Skip them if:

• You're on a solo project with no repeated workflows
• The default agent works fine
• You don't have clear role boundaries

Use them when:

• You have repeating multi-step workflows
• You need different tool access for different tasks
• You're coordinating with a team
• You want consistent personas for subagent delegation

Token Efficiency

Agent files are processed on every request. Wasteful formatting burns tokens:

• Skip **bold** and _italic_. LLMs ignore visual formatting.
• Use - not - [ ]. Checkboxes are for humans.
• Be direct. Verbose explanations dilute context.
• One blank line between sections is enough.

Long files make models less likely to follow all instructions. If you're using an LLM to draft agent files, watch for this. Models add formatting "for readability" that wastes your token budget.

Experimental Features

Some features are experimental (APIs may change):

• Organization-level agents: Shared across repos in your GitHub org
• Nested AGENTS.md discovery: Auto-find AGENTS.md in parent directories
• Subagent inference: Use custom agents as subagents in multi-step tasks

The Reality Check

Custom agents are powerful, but stochastic limitations apply. Agents will sometimes ignore instructions or misuse tools.

Use agents for the "vibe" of the workflow. Use deterministic tools (ESLint, tests, CI) for enforcement.

Practical Advice

Start simple:

1. Level 1: Use the default agent. Most tasks don't need specialization.
2. Level 2: Create one specialized agent for your most common workflow.
3. Level 3: Add handoffs to chain agents for multi-step tasks.
4. Level 4: Build a full team with clear responsibilities.

Don't over-engineer. If you're spending more time configuring agents than saving, you've gone too far.

Further Reading

• VS Code: Custom Agents Documentation
• GitHub: Creating Custom Agents
• GitHub: Custom Agents Configuration Reference
• Awesome Copilot: Community Agent Examples

---

Model Note: This article was written with the help of Claude Sonnet 4. No other models involved.

Return to Series Overview