Agents

# Custom Agent File Guidelines

Instructions for creating effective and maintainable custom agent files that provide specialized expertise for specific development tasks in GitHub Copilot.

Project Context

- Target audience: Developers creating custom agents for GitHub Copilot

- File format: Markdown with YAML frontmatter

- File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)

- Location: `.github/agents/` directory (repository-level) or `agents/` directory (organization/enterprise-level)

- Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks

- Official documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents

Required Frontmatter

Every agent file must include YAML frontmatter with the following fields:

---
description: 'Brief description of the agent purpose and capabilities'
name: 'Agent Display Name'
tools: ['read', 'edit', 'search']
model: 'Claude Sonnet 4.5'
target: 'vscode'
---

Core Frontmatter Properties

#### **description** (REQUIRED)

- Single-quoted string, clearly stating the agent's purpose and domain expertise

- Should be concise (50-150 characters) and actionable

- Example: `'Focuses on test coverage, quality, and testing best practices'`

#### **name** (OPTIONAL)

- Display name for the agent in the UI

- If omitted, defaults to filename (without `.md` or `.agent.md`)

- Use title case and be descriptive

- Example: `'Testing Specialist'`

#### **tools** (OPTIONAL)

- List of tool names or aliases the agent can use

- Supports comma-separated string or YAML array format

- If omitted, agent has access to all available tools

- See "Tool Configuration" section below for details

#### **model** (STRONGLY RECOMMENDED)

- Specifies which AI model the agent should use

- Supported in VS Code, JetBrains IDEs, Eclipse, and Xcode

- Example: `'Claude Sonnet 4.5'`, `'gpt-4'`, `'gpt-4o'`

- Choose based on agent complexity and required capabilities

#### **target** (OPTIONAL)

- Specifies target environment: `'vscode'` or `'github-copilot'`

- If omitted, agent is available in both environments

- Use when agent has environment-specific features

#### **user-invocable** (OPTIONAL)

- Boolean controlling whether the agent appears in the agents dropdown in chat

- Default: `true` if omitted

- Set to `false` to create agents that are only accessible as subagents or programmatically

#### **disable-model-invocation** (OPTIONAL)

- Boolean controlling whether the agent can be invoked as a subagent by other agents

- Default: `false` if omitted

- Set to `true` to prevent subagent invocation while keeping it available in the picker

#### **metadata** (OPTIONAL, GitHub.com only)

- Object with name-value pairs for agent annotation

- Example: `metadata: { category: 'testing', version: '1.0' }`

- Not supported in VS Code

#### **mcp-servers** (OPTIONAL, Organization/Enterprise only)

- Configure MCP servers available only to this agent

- Only supported for organization/enterprise level agents

- See "MCP Server Configuration" section below

#### **handoffs** (OPTIONAL, VS Code only)

- Enable guided sequential workflows that transition between agents with suggested next steps

- List of handoff configurations, each specifying a target agent and optional prompt

- After a chat response completes, handoff buttons appear allowing users to move to the next agent

- Only supported in VS Code (version 1.106+)

- See "Handoffs Configuration" section below for details

Handoffs Configuration

Handoffs enable you to create guided sequential workflows that transition seamlessly between custom agents. This is useful for orchestrating multi-step development workflows where users can review and approve each step before moving to the next one.

Common Handoff Patterns

- **Planning → Implementation**: Generate a plan in a planning agent, then hand off to an implementation agent to start coding

- **Implementati