custom-agents | SkillBundle

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:

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:

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:

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:

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

Pattern 2: Path-specific Instructions

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

Pattern 3: Custom Agent Profile

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

Pattern 4: Test Writer Agent

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

Pattern 5: Agentic Workflow Integration

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

File: .github/agents/code-reviewer.md

Integration with gh-aw

The gh-aw (GitHub Agentic Workflows) tool supports custom agent files through the imports field in workflow frontmatter. Any markdown files under the .github/agents/ directory are treated as custom agent files when imported.

Preferred way to install skills in workflows

Use the skills: frontmatter field as the preferred way to install external skills for workflow runs. This installs skills during activation and persists them correctly between jobs.

Use imports: for workflow prompt/context files (including local custom agent files), not as the primary skill installation path.

Configuration

Supported Engines

Custom agent files are supported by the following engines:

Copilot - Uses --agent <path> flag to load custom agent file
Claude - Prepends agent file content to the workflow prompt
Codex - Prepends agent file content to the workflow prompt

File Path Resolution

Agent files are imported via the imports field
Must be markdown files located under .github/agents/ directory
Only one agent file is allowed per workflow
File is validated during workflow compilation
Checkout step is automatically added if agent file is imported

Example Workflow with Custom Agent

Best Practices

1. Keep Instructions Focused

Each agent should have a clear, specific purpose
Avoid mixing unrelated concerns in a single agent
Create multiple specialized agents rather than one general-purpose agent

2. Be Explicit and Specific

Provide concrete examples of expected behavior
Define clear success criteria
Specify edge cases and error handling

3. Use Appropriate Scoping

Repository-wide instructions for universal standards
Path-specific instructions for framework or directory-specific rules
Custom agents for task-specific workflows

4. Test Agent Behavior

Verify agent follows instructions correctly
Test with various input scenarios
Iterate based on actual agent performance

5. Maintain and Update

Keep instructions current with codebase changes
Review and refine based on agent performance
Remove outdated or conflicting instructions

6. Security Considerations

Limit tool access to what's necessary
Be cautious with file deletion permissions
Use secrets for sensitive configuration
Review agent actions regularly

Common Patterns

Documentation Agent

Refactoring Agent

Security Auditor

Migration Assistant

Issue Management Agent

Pull Request Assistant

Troubleshooting

Agent Not Following Instructions

Make instructions more explicit and specific
Provide concrete examples
Break down complex instructions into steps
Ensure instructions don't conflict

Tool Access Issues

Verify tools are listed in tools array
Check agent has necessary permissions
Ensure tools are available in the environment

Path Targeting Not Working

Verify glob patterns are correct
Check file paths match patterns
Ensure applyTo is only used in .instructions.md files

Custom Agent File Not Found

Verify agent file is imported in the imports field
Ensure file exists and is committed under .github/agents/ directory
Confirm agent file path is correct in imports list
Remember: only one agent file is allowed per workflow

References

GitHub Copilot Agent Filess Configuration - Official reference for custom agent configuration including tool aliases
GitHub Copilot Custom Instructions Documentation
About Custom Agents
GitHub Blog: Custom Instructions Support
GitHub Blog: AGENTS.md Support

Examples in This Repository

The gh-aw repository uses custom agent files for performance engineering guides:

.github/copilot/instructions/ci-performance.md - CI/CD optimization
.github/copilot/instructions/workflow-performance.md - Workflow efficiency
.github/copilot/instructions/build-performance.md - Build optimization
.github/copilot/instructions/cli-performance.md - CLI performance

These files provide specialized guidance for performance engineering tasks and demonstrate the custom agent file format in practice.**

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:

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:

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:

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:

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

Pattern 2: Path-specific Instructions

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

Pattern 3: Custom Agent Profile

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

Pattern 4: Test Writer Agent

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

Pattern 5: Agentic Workflow Integration

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

File: .github/agents/code-reviewer.md

Integration with gh-aw

Preferred way to install skills in workflows

Use the skills: frontmatter field as the preferred way to install external skills for workflow runs. This installs skills during activation and persists them correctly between jobs.

Use imports: for workflow prompt/context files (including local custom agent files), not as the primary skill installation path.

Configuration

Supported Engines

Custom agent files are supported by the following engines:

Copilot - Uses --agent <path> flag to load custom agent file
Claude - Prepends agent file content to the workflow prompt
Codex - Prepends agent file content to the workflow prompt

File Path Resolution

Agent files are imported via the imports field
Must be markdown files located under .github/agents/ directory
Only one agent file is allowed per workflow
File is validated during workflow compilation
Checkout step is automatically added if agent file is imported

Example Workflow with Custom Agent

Best Practices

1. Keep Instructions Focused

Each agent should have a clear, specific purpose
Avoid mixing unrelated concerns in a single agent
Create multiple specialized agents rather than one general-purpose agent

2. Be Explicit and Specific

Provide concrete examples of expected behavior
Define clear success criteria
Specify edge cases and error handling

3. Use Appropriate Scoping

Repository-wide instructions for universal standards
Path-specific instructions for framework or directory-specific rules
Custom agents for task-specific workflows

4. Test Agent Behavior

Verify agent follows instructions correctly
Test with various input scenarios
Iterate based on actual agent performance

5. Maintain and Update

Keep instructions current with codebase changes
Review and refine based on agent performance
Remove outdated or conflicting instructions

6. Security Considerations

Limit tool access to what's necessary
Be cautious with file deletion permissions
Use secrets for sensitive configuration
Review agent actions regularly

Common Patterns

Documentation Agent

Refactoring Agent

Security Auditor

Migration Assistant

Issue Management Agent

Pull Request Assistant

Troubleshooting

Agent Not Following Instructions

Make instructions more explicit and specific
Provide concrete examples
Break down complex instructions into steps
Ensure instructions don't conflict

Tool Access Issues

Verify tools are listed in tools array
Check agent has necessary permissions
Ensure tools are available in the environment

Path Targeting Not Working

Verify glob patterns are correct
Check file paths match patterns
Ensure applyTo is only used in .instructions.md files

Custom Agent File Not Found

Verify agent file is imported in the imports field
Ensure file exists and is committed under .github/agents/ directory
Confirm agent file path is correct in imports list
Remember: only one agent file is allowed per workflow

References

GitHub Copilot Agent Filess Configuration - Official reference for custom agent configuration including tool aliases
GitHub Copilot Custom Instructions Documentation
About Custom Agents
GitHub Blog: Custom Instructions Support
GitHub Blog: AGENTS.md Support

Examples in This Repository

The gh-aw repository uses custom agent files for performance engineering guides:

.github/copilot/instructions/ci-performance.md - CI/CD optimization
.github/copilot/instructions/workflow-performance.md - Workflow efficiency
.github/copilot/instructions/build-performance.md - Build optimization
.github/copilot/instructions/cli-performance.md - CLI performance

These files provide specialized guidance for performance engineering tasks and demonstrate the custom agent file format in practice.**