custom-agents

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub Custom Agent File Format

This document describes the GitHub custom agent file format used by GitHub Copilot to provide repository-specific or task-specific instructions to AI coding agents.

## Overview

GitHub Copilot supports custom agent instructions through Markdown files with YAML frontmatter. These files allow you to define specialized agent behaviors, tool access, and custom workflows that tailor Copilot's behavior to your repository's needs.

## File Locations

Custom agent files can be placed in several locations, each serving a different 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

```markdown
# 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

```yaml
# 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:

From kaushal-waygood/agentic-self-healing-ci, MIT.

More from kaushal-waygood/agentic-self-healing-ci