Skip to main content

​
Creating Custom Agents

Custom agents are specialized GitHub Copilot agents with tailored expertise, tools, and instructions for specific tasks. This guide shows you how to create effective custom agents using real examples from the community.

​
What are Custom Agents?

Custom agents are markdown files with YAML frontmatter that define:
  • Agent identity and expertise - What the agent specializes in
  • Available tools - Which operations the agent can perform
  • Instructions - How the agent should work and respond
  • Model selection - Which AI model powers the agent
Custom agents live in .github/agents/ (repository-level) or agents/ (organization/enterprise-level).

​
Anatomy of a Custom Agent

Here’s the basic structure: 
---
description: 'Brief description of agent purpose and capabilities'
name: 'Agent Display Name'
tools: ['read', 'edit', 'search']
model: 'Claude Sonnet 4.5'
---

# Agent Name

Detailed instructions for how the agent should behave...

​
Quick Start: Your First Agent

Let’s create a simple code review agent:
1

Create the agent file

Create .github/agents/code-reviewer.agent.md:
---
description: 'Review code for quality, security, and best practices'
name: 'Code Reviewer'
tools: ['read', 'search']
model: 'Claude Sonnet 4.5'
---

# Code Review Agent

You are a code review specialist. Your task is to:

1. Check code quality and maintainability
2. Identify security issues and vulnerabilities
3. Verify adherence to project standards
4. Suggest improvements

Provide constructive feedback on the implementation.
2

Test the agent

  1. Reload VS Code or refresh GitHub.com
  2. Select “Code Reviewer” from the Copilot Chat dropdown
  3. Ask it to review a file or code snippet
3

Iterate and refine

Based on the agent’s responses, adjust the instructions and tools to improve performance

​
Real-World Example: PR Comment Addresser

Here’s a production agent from the Awesome Copilot repository: 
---
description: "Address PR comments"
name: 'Universal PR Comment Addresser'
tools:
  [
    "changes",
    "codebase",
    "editFiles",
    "extensions",
    "fetch",
    "findTestFiles",
    "githubRepo",
    "new",
    "openSimpleBrowser",
    "problems",
    "runCommands",
    "runTasks",
    "runTests",
    "search",
    "searchResults",
    "terminalLastCommand",
    "terminalSelection",
    "testFailure",
    "usages",
    "vscodeAPI",
    "microsoft.docs.mcp",
    "github",
  ]
---

# Universal PR Comment Addresser

Your job is to address comments on your pull request.

## When to address or not address comments

Reviewers are normally, but not always right. If a comment does not make sense to you,
ask for more clarification. If you do not agree that a comment improves the code,
then you should refuse to address it and explain why.

## Addressing Comments

- You should only address the comment provided not make unrelated changes
- Make your changes as simple as possible and avoid adding excessive code
- You should always change all instances of the same issue
- Always add test coverage for your changes if not already present

## After Fixing a comment

### Run tests

If you do not know how, ask the user.

### Commit the changes

You should commit changes with a descriptive commit message.

### Fix next comment

Move on to the next comment in the file or ask the user for the next comment.
This agent uses comprehensive tool access because it needs to read code, make edits, run tests, and commit changes. Always grant the minimum tools needed for the agent’s purpose.

​
Frontmatter Properties

​
Required Properties

​
description
string
required
Brief, single-quoted description of the agent’s purpose (50-150 characters)
description: 'Focuses on test coverage, quality, and testing best practices'

​
Optional Properties

​
name
string
Display name for the agent in the UI (defaults to filename if omitted)
name: 'Testing Specialist'
​
tools
array
List of tools the agent can use. If omitted, agent has access to all tools.
tools: ['read', 'edit', 'search', 'execute']
​
model
string
AI model to use (strongly recommended)
model: 'Claude Sonnet 4.5'
model: 'gpt-4o'
​
infer
boolean
default:"true"
Whether Copilot can automatically use this agent based on context
infer: false  # Require manual selection

​
Tool Configuration

​
Standard Tool Aliases

All tool names are case-insensitive:
  • read - Read file contents
  • edit - Edit and modify files
  • search - Search for files or text in files (Grep, Glob)

​
Tool Selection Examples

# Omit tools property entirely
tools: ['*']

​
Agent Instructions

The markdown content below the frontmatter defines agent behavior:

​
Structure Template

# Agent Name

## Role

[Who the agent is and its primary responsibility]

## Objectives

1. [What the agent should accomplish]
2. [Key goals and outcomes]

## Approach

- [How the agent should work]
- [Methodology and process]

## Guidelines

- [What to do and avoid]
- [Quality standards]
- [Constraints and boundaries]

## Output Format

[Expected output structure and format]

​
Best Practices

Use imperative mood (“Analyze”, “Generate”) and avoid vague terms.Good: “Analyze code for security vulnerabilities using OWASP Top 10”Avoid: “Help with security”
Explicitly state what the agent should and shouldn’t do.
## Guidelines

- Focus ONLY on security issues
- Do NOT refactor code
- Do NOT modify functionality
Show the agent what good output looks like.
## Example Output

**Security Issue**: SQL Injection vulnerability
**Location**: `user_controller.py:42`
**Severity**: High
**Fix**: Use parameterized queries
One agent should do one thing well. Create multiple agents rather than one that does everything.

​
Common Agent Patterns

Testing Specialist

Tools: All tools for comprehensive test creationFocus: Analyze code, identify gaps, write tests, avoid production changes

Code Reviewer

Tools: read, search onlyFocus: Analyze and suggest improvements, no direct modifications

Refactoring Specialist

Tools: read, search, editFocus: Improve code structure while maintaining behavior

Security Auditor

Tools: read, search, webFocus: Identify vulnerabilities, check against OWASP, report findings

​
Advanced: Agent Handoffs

Create guided sequential workflows that transition between agents: 
---
description: 'Generate an implementation plan'
name: 'Planner'
tools: ['search', 'read']
handoffs:
  - label: Implement Plan
    agent: implementer
    prompt: 'Implement the plan outlined above.'
    send: false
---

# Planner Agent

You are a planning specialist. Your task is to:
1. Analyze requirements
2. Break down work into steps
3. Generate detailed implementation plan
4. Identify testing requirements

Do not write any code - focus only on planning.
When the planner completes, users see a button “Implement Plan” that switches to the implementer agent.
Handoffs are currently supported in VS Code 1.106+ only.

​
File Organization

​
Repository-Level Agents

.github/agents/
  ├── code-reviewer.agent.md
  ├── test-specialist.agent.md
  └── security-auditor.agent.md
Available only in this repository.

​
Organization-Level Agents

agents/
  ├── company-standards.agent.md
  ├── compliance-checker.agent.md
  └── architecture-reviewer.agent.md
Available across all repositories in the organization.

​
Testing Your Agent

1

Manual Testing

  1. Create the agent file with proper frontmatter
  2. Reload VS Code or refresh GitHub.com
  3. Select the agent from Copilot Chat dropdown
  4. Test with representative queries
  5. Verify tool access works as expected
2

Refinement

Based on agent responses:
  • Adjust instructions for clarity
  • Add or remove tools as needed
  • Refine output format expectations
3

Production

  • Document any special configuration
  • Get peer review for complex agents
  • Test with real use cases

​
Common Mistakes to Avoid

Missing Description: Every agent MUST have a description field wrapped in single quotes.
Too Many Tools: Don’t grant execute access unless the agent genuinely needs to run commands. Use principle of least privilege.
Vague Instructions: “Help with testing” is too vague. Be specific: “Write unit tests using Jest with 80% coverage”.
Wrong File Location: Repository agents go in .github/agents/, not agents/.

​
Example Agents from the Community

Explore real production agents: Browse all community agents →

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us