---
topic: copilot-cli-agents
source_keys:
  - github-copilot-custom-agents-config
  - github-blog-copilot-cli-agents
---

## Overview

GitHub Copilot CLI agents are defined as Markdown files with `.agent.md` extension and YAML frontmatter. They live in the `.github/agents/` directory of a repository and are version-controlled with the codebase. Users invoke them via the `/agent` slash command in the CLI.

## File format

```markdown
---
name: Accessibility Expert
description: Expert assistant for web accessibility (WCAG 2.1/2.2)
model: GPT-4.1
tools:
  - codebase
  - edit/editFiles
  - search
---

# Accessibility Expert

You are a web accessibility expert. Focus on WCAG 2.1/2.2 compliance...
```

The body (below frontmatter) contains the agent's instructions in Markdown. Maximum 30,000 characters.

## Supported frontmatter fields

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | String | Recommended | Display identifier for the agent |
| `description` | String | Required | Purpose and capabilities — what this agent does |
| `target` | String | No | `vscode`, `github-copilot`, or omit for both |
| `model` | String | No | Model to use (e.g., `GPT-4.1`, `claude-opus-4-8`). Inherits default if unset. |
| `tools` | List | No | Tools the agent can use. Defaults to all tools if omitted. |
| `disable-model-invocation` | Boolean | No | When `true`, requires manual agent selection. |
| `user-invocable` | Boolean | No | Whether user can manually select this agent. Defaults to `true`. |
| `mcp-servers` | Object | No | Additional MCP server configurations. Not used in VS Code/IDE agents. |
| `metadata` | Object | No | Key-value annotation pairs. Not applicable to IDE agents. |

## Tools field

Tools can be configured three ways:

- **All tools** (default): omit the `tools` property, or use `tools: ["*"]`
- **Specific tools**: list names, e.g. `tools: ["codebase", "edit/editFiles", "search"]`
- **No tools**: `tools: []`

Available tool aliases (case-insensitive): `execute`, `read`, `edit`, `search`, `agent`, `web`, `todo`.

MCP server tools use namespacing: `mcp-server-name/tool-name` or `mcp-server-name/*` for all tools from a server.

Some available tools: `gh`, `git`, `codebase`, `search`, `githubRepo`, `runCommands`, `runTests`, `edit/editFiles`, `terraform`, `conftest`, `jq`, `curl`, `semgrep`, `trivy`, `gitleaks`.

## File location

Copilot CLI agents live in `.github/agents/` in the repository root. The filename uses the `.agent.md` extension (e.g., `accessibility.agent.md`).

## Plugin placement (this repo)

Per the cross-compat reference, plugin agents for Copilot CLI use the `.agent.md` naming:
- Claude Code reads: `agents/<name>.md`
- Copilot CLI reads: `agents/<name>.agent.md`

Both files share the same system prompt body. Only the frontmatter differs: Copilot uses `tools:` as an array with different tool names; Claude Code uses `tools:` as comma-separated internal tool names.

## Fields not supported in Copilot CLI

These Claude Code agent fields have no Copilot CLI equivalent:
- `permissionMode`
- `maxTurns`
- `skills` (Claude-specific skill injection)
- `mcpServers` (inline per-agent MCP — not supported in VS Code/IDE)
- `hooks`
- `memory`
- `background`
- `effort`
- `isolation`
- `color`
- `initialPrompt`
- `disallowedTools`