GitHub Custom Agent File Format

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