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