custom-agents

GitHub Custom Agent File Format

Use this reference for the GitHub custom agent file format.

Overview

GitHub Copilot reads custom agent instructions from Markdown files with YAML frontmatter. Use them to define specialized behavior, tool access, and workflows for your repository.

File Locations

Place custom agent files in these locations based on scope:

1. Repository-wide Instructions

• File: .github/copilot-instructions.md
• Scope: Applies to all code generation in the repository
• Use case: General coding standards, security requirements, testing practices

2. Path-specific Instructions

• Directory: .github/instructions/
• Pattern: *.instructions.md (e.g., frontend.instructions.md, backend.instructions.md)
• Scope: Can target specific directories or file patterns using applyTo in frontmatter
• Use case: Framework-specific guidelines, component-specific rules

3. Custom Agent Profiles

• Directory: .github/agents/ or .github/copilot/instructions/
• Pattern: AGENTS.md, *.md (e.g., readme-creator.md, test-writer.md)
• Scope: Defines specialized agents with specific capabilities and instructions
• Use case: Task-specific agents (documentation, testing, refactoring)

4. agentic workflow integration

• Location: Imported via imports field in workflow frontmatter
• Pattern: Any markdown files under .github/agents/ directory
• Scope: Custom agent for specific agentic workflow execution
• Use case: Workflow-specific agent configuration
• Important: Only one agent file is allowed per workflow

File Format

Basic Structure

# YAML frontmatter (configuration)
name: agent-name
description: Brief description of agent's purpose

# Markdown body (instructions)

Your natural language instructions for the agent go here.

Complete YAML Frontmatter Schema

# Required fields
name: agent-identifier              # Unique identifier for the agent

# Optional descriptive fields
description: >                      # Multi-line description of agent's purpose
  Agent specializing in specific tasks

# Optional instruction fields
prompt: |                          # Freeform instructions (alternative to markdown body)
  Your instructions here

# Optional tool configuration
tools:                             # List of allowed tools for this agent
  - createFile
  - editFiles
  - codeSearch
  - search

# Optional path targeting (for .instructions.md files)
applyTo:                          # Glob patterns for targeted files/directories
  - "src/frontend/**"
  - "**/*.tsx"

# Optional MCP server configuration (enterprise/org only)
mcp-server:                       # External MCP server configuration
  url: https://my-mcp-server.com
  api-key: ${{ secrets.MCPSERVER_API_KEY }}

# Optional settings
settings:                         # Custom runtime or connection settings
  key: value

Field Descriptions

Core Fields

name (string, required for agent profiles)

• Unique identifier for the custom agent
• Used to reference the agent in workflows or assignments
• Convention: lowercase with hyphens (e.g., readme-creator, test-writer)

description (string, optional)

• Human-friendly description of the agent's focus and behavior
• Helps users understand what the agent specializes in
• Can be multi-line using YAML's > or | syntax

prompt (string, optional)

• Alternative to using the markdown body for instructions
• Contains freeform natural language instructions
• Use YAML's | (literal) or > (folded) for multi-line content
• If both prompt and markdown body exist, they are typically combined

Tool Configuration

tools (array of strings, optional)

• List of tools the agent is allowed to use
• If omitted or set to ["*"], agent has access to all available tools
• Tool names are case-insensitive
• Supports both GitHub's standard tool aliases and legacy naming conventions

GitHub Standard Tool Aliases:

GitHub Copilot defines a standardized set of tool aliases for custom agents:

• read - Access and read contents of files or code
• edit - Make changes in code files, apply edits or refactoring
• search - Search codebase for keywords, references, or patterns
• pr - Create, manage, or update pull requests
• issue - Create, manage, or update issues

Legacy Tool Names:

For backward compatibility, these legacy tool names are still supported:

• createFile - Create new files (use edit instead)
• editFiles - Modify existing files (use edit instead)
• deleteFiles - Remove files (use edit instead)
• codeSearch - Semantic code search (use search instead)
• runCommand - Execute shell commands
• getFile - Read file contents (use read instead)
• listFiles - List directory contents (use read instead)

MCP Server Tool Prefixes:

When using Model Context Protocol (MCP) servers, you can specify tools with server prefixes:

• Single tool: my-mcp-server/tool-name
• All tools from a server: my-mcp-server/*

Examples:

# Using standard tool aliases
tools:
  - read
  - edit
  - search

# Enable all tools with wildcard
tools: ["*"]

# Using legacy names (still supported)
tools:
  - editFiles
  - createFile
  - search

# Mixed standard and MCP server tools
tools:
  - read
  - edit
  - github-mcp/create_issue
  - custom-mcp/*

# Empty list disables all tools
tools: []

Path Targeting

applyTo (array of strings, optional)

• Only used in .instructions.md files
• Specifies glob patterns for files/directories these instructions apply to
• Supports wildcards: * (any characters), ** (any directories)
• Multiple patterns can be specified

Example:

applyTo:
  - "src/frontend/**/*.tsx"
  - "src/frontend/**/*.ts"
  - "components/**"

Enterprise Features

mcp-server (object, optional)

• Configuration for external MCP (Model Context Protocol) servers
• Typically used in enterprise or organization settings
• Allows integration with custom tools and services

Fields:

• url (string): MCP server endpoint
• api-key (string): Authentication key (use GitHub secrets)

Example:

mcp-server:
  url: https://internal-tools.company.com/mcp
  api-key: ${{ secrets.INTERNAL_MCP_KEY }}

settings (object, optional)

• Custom runtime or connection settings
• Key-value pairs for agent-specific configuration
• Format and available keys depend on the agent implementation

Usage Patterns

Pattern 1: Repository-wide Standards

File: .github/copilot-instructions.md

description: Repository-wide coding standards

# Coding Standards

## Style Guide
- Use single quotes in JavaScript/TypeScript
- Follow ESLint configuration in `.eslintrc.json`
- Maximum line length: 100 characters

## Security
- Always set `httpOnly` and `secure` flags for cookies
- Validate all user input
- Use parameterized queries for database access

## Testing
- All new code must include Jest tests
- Aim for >80% code coverage
- Test edge cases and error conditions

Pattern 2: Path-specific Instructions

File: .github/instructions/frontend.instructions.md

description: Frontend development guidelines
applyTo:
  - "src/frontend/**"
  - "components/**"

# Frontend Development Guidelines

## Component Structure
- Use React functional components with hooks
- Prefer composition over inheritance
- Keep components small and focused (< 150 lines)

## Styling
- Use CSS Modules for component styles
- Follow BEM naming convention
- Use Tailwind utility classes where appropriate

## State Management
- Use React Context for global state
- Keep local state in components when possible
- Use reducers for complex state logic

Pattern 3: Custom Agent Profile

File: .github/agents/readme-creator.md

name: readme-creator
description: Agent specializing in creating and improving README files
tools:
  - read
  - edit
  - search

# README Creator Agent

You are a documentation specialist focused on creating clear, comprehensive README files.

## Responsibilities
- Create well-structured README.md files for projects
- Include all standard sections: Overview, Installation, Usage, Contributing
- Generate accurate code examples
- Ensure documentation is up-to-date with codebase

## Style Guidelines
- Use clear, concise language
- Include code examples with syntax highlighting
- Add badges for build status, coverage, version
- Organize with logical heading hierarchy
- Include a table of contents for long READMEs

## Quality Standards
- Verify all code examples are accurate
- Test installation instructions
- Ensure links are valid and working
- Check for proper Markdown formatting

Pattern 4: Test Writer Agent

File: .github/agents/test-writer.md

name: test-writer
description: Specialized agent for writing comprehensive test suites
tools:
  - read
  - edit
  - search

# Test Writer Agent

You specialize in creating comprehensive, well-structured test suites.

## Testing Framework
- Use Jest for JavaScript/TypeScript
- Follow AAA pattern: Arrange, Act, Assert
- Use descriptive test names: "should [expected behavior] when [condition]"

## Test Coverage
- Write unit tests for all public functions
- Create integration tests for API endpoints
- Add edge case tests (null, undefined, empty, boundary values)
- Test error conditions and exception handling

## Test Organization
- Group related tests with `describe` blocks
- Use `beforeEach` and `afterEach` for setup/teardown
- Keep tests independent and isolated
- Mock external dependencies

## Best Practices
- One assertion per test when possible
- Use test data builders for complex objects
- Avoid test interdependence
- Keep tests fast (< 1 second each)

Pattern 5: Agentic Workflow Integration

File: .github/workflows/code-review.md

on:
  pull_request

---

*Content truncated.*