Custom Agent Creator

GitHub Copilot Custom Agent Creator

Create specialized GitHub Copilot agents with tailored expertise for specific development tasks. Custom agents are Markdown files with YAML frontmatter that define the agent's identity, capabilities, tool access, and behavioral instructions.

Quick Start

Agent File Location

File Naming

• Extension: .agent.md or just .md
• Allowed characters: ., -, _, a-z, A-Z, 0-9
• Examples: test-specialist.agent.md, code-reviewer.agent.md

Agent Profile Structure

---
name: agent-name
description: Required description of the agent's purpose
tools: ["read", "edit", "search"]
target: vscode
---

Your agent's prompt and instructions go here.
Define behavior, expertise, and guidelines.
Maximum 30,000 characters.

YAML Frontmatter Properties

Tools Configuration

Enable All Tools (Default)

# Option 1: Omit tools property entirely
---
name: my-agent
description: Agent with all tools available
---

# Option 2: Explicit wildcard
---
name: my-agent
description: Agent with all tools available
tools: ["*"]
---

Enable Specific Tools

---
name: my-agent
description: Read-only agent
tools: ["read", "search"]
---

Disable All Tools

---
name: my-agent
description: Chat-only agent with no tools
tools: []
---

Tool Aliases

MCP Server Tools

# All tools from an MCP server
tools: ["my-mcp-server/*"]

# Specific tool from MCP server
tools: ["my-mcp-server/specific-tool"]

# Built-in MCP servers
tools: ["github/*", "playwright/*"]

# VS Code extension tools
tools: ["azure.some-extension/some-tool"]

Built-in MCP Servers

Writing Effective Prompts

Prompt Structure Best Practices

1. Role Definition: Start with who/what the agent is
2. Responsibilities: List core responsibilities
3. Guidelines: Provide specific behavioral guidance
4. Constraints: Define boundaries and limitations
5. Output Format: Specify expected output style

Example Prompt Structure

---
name: my-specialist
description: Description here
---

You are a [role] specialized in [domain]. Your responsibilities:

- [Primary responsibility]
- [Secondary responsibility]
- [Additional responsibilities]

## Guidelines

- [Guideline 1]
- [Guideline 2]

## Constraints

- [What NOT to do]
- [Boundaries]

## Output Format

[How to format responses]

Example Agent Profiles

Testing Specialist

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

Implementation Planner

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

Code Reviewer

---
name: code-reviewer
description: Reviews code for quality, security, performance, and best practices
tools: ["read", "search"]
---

You are a senior code reviewer focused on improving code quality. Your responsibilities:

- Review code for bugs, security vulnerabilities, and performance issues
- Check adherence to coding standards and best practices
- Identify potential edge cases and error handling gaps
- Suggest improvements for readability and maintainability
- Verify proper error handling, logging, and documentation

Provide constructive feedback with specific suggestions and code examples. Prioritize critical issues over style preferences. Reference relevant documentation when applicable.

Documentation Writer

---
name: doc-writer
description: Creates and maintains comprehensive documentation for codebases
tools: ["read", "search", "edit"]
---

You are a technical documentation specialist. Your responsibilities:

- Write clear, comprehensive README files
- Create API documentation with examples
- Document architecture decisions and system design
- Write inline code comments where helpful
- Create user guides and tutorials

Use clear, concise language. Include code examples where appropriate. Structure documentation with proper headings and navigation. Keep documentation up-to-date with code changes.

Security Auditor

---
name: security-auditor
description: Identifies security vulnerabilities and recommends fixes
tools: ["read", "search"]
---

You are a security specialist focused on identifying and addressing vulnerabilities. Your responsibilities:

- Analyze code for common security vulnerabilities (OWASP Top 10)
- Review authentication and authorization implementations
- Check for sensitive data exposure and improper handling
- Identify injection vulnerabilities (SQL, XSS, command injection)
- Review dependency security and suggest updates

Provide detailed security reports with severity ratings. Include remediation steps and code examples for fixes. Reference relevant security standards and best practices.

MCP Server Configuration (Org/Enterprise Only)

---
name: my-agent-with-mcp
description: Agent with custom MCP server
tools: ["read", "edit", "custom-mcp/tool-1"]
mcp-servers:
  custom-mcp:
    type: local
    command: some-command
    args: ["--arg1", "--arg2"]
    tools: ["*"]
    env:
      API_KEY: ${{ secrets.API_KEY }}
      BASE_URL: ${{ var.BASE_URL }}
---

Agent prompt here...

Environment Variable Syntax

Target Environments

# VS Code only
target: vscode

# GitHub.com only
target: github-copilot

# Both environments (default)
# Omit the target property

Agent Processing Rules

Naming Conflicts (Precedence)

1. Repository-level (highest priority)
2. Organization-level
3. Enterprise-level (lowest priority)

Versioning

• Based on Git commit SHAs
• Create branches/tags for different versions
• Pull request interactions use consistent version

Best Practices

Agent Design

1. Single Responsibility: Focus each agent on one domain
2. Clear Description: Make the purpose immediately obvious
3. Minimal Tools: Only enable tools the agent needs
4. Specific Prompts: Provide detailed behavioral guidance
5. Examples: Include examples of expected output

Prompt Writing

1. Be Specific: Avoid vague instructions
2. Set Boundaries: Define what NOT to do
3. Format Output: Specify expected response format
4. Include Context: Provide domain-specific knowledge
5. Test Iteratively: Refine based on actual usage

Tool Selection

1. Least Privilege: Only enable necessary tools
2. Read-Only First: Start with read/search, add edit later
3. Document Rationale: Explain why tools are needed
4. Test Tool Usage: Verify agent uses tools correctly

Resources

• Creating Custom Agents
• Custom Agents Configuration
• Custom Agents in VS Code
• Awesome Copilot Agents

File References

For detailed documentation, see:

• references/yaml-properties.md - Complete YAML property reference
• references/tools-reference.md - All available tools and aliases
• references/mcp-configuration.md - MCP server configuration guide
• examples/test-specialist.agent.md - Testing agent template
• examples/code-reviewer.agent.md - Code review agent template
• examples/security-auditor.agent.md - Security audit agent template
• scripts/validate-agent.ts - Agent file validation utility

Converted and distributed by TomeVault — claim your Tome and manage your conversions.