# Subagents in Copilot CLI

Define a read-only reviewer custom agent for ticket-service and learn how Copilot CLI loads, scopes, invokes and limits custom agents.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/subagents/copilot-cli

This page covers Copilot CLI. The cloud agent also reads repository profiles from `.github/agents/`, but property support differs by environment (for example `target`, and `github/...` instead of `github-mcp-server/...` tool names).

## At a glance

| | Copilot CLI |
|---|---|
| Term | Custom agents (profiles); a run is a subagent with its own context window |
| Configured in | `.github/agents/NAME.agent.md` (repository), `~/.copilot/agents/` (user) |
| Loads / runs | Profiles load at CLI start (restart after adding one). The main agent delegates by description, or you select one |
| Scope & precedence | User, then repository, then `.claude/agents/`, added roots, plugins, org and enterprise; first match per ID wins |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Create the profile (or `/agent` → **Create new agent** → **Project**) | `.github/agents/reviewer.agent.md` |
| 2 | Restart the CLI so the profile loads | Terminal |
| 3 | Ask for a review after implementing an issue | Prompt, `/agent`, or `copilot --agent reviewer -p "..."` |

```markdown
---
name: reviewer
description: Reviews the current change in ticket-service against the issue's acceptance criteria and the team conventions. Use after implementing an issue, before opening a pull request. Read-only.
tools: [read, search, execute, github-mcp-server/issue_read]
model: <model>   # a different model from your session gives a second opinion
include-custom-instructions: true
---
1. Run `git diff main...HEAD` and read the changed files.
2. Read the issue (number in the prompt or branch name) with `issue_read`.
3. Check every acceptance criterion against the diff.
4. Check conventions: a route change has a test in `test/`; files in `src/db/migrations/` are never hand-edited.
5. Return pass or fail per criterion, then findings as `file:line` with a one-line reason.
6. Never edit files or run commands that change the repository.
```

```shell
copilot --agent reviewer -p "Review the change for issue 42"
```

The profile omits `edit`, so the agent has no editing tool. `execute` grants the whole shell, because the documentation doesn't specify a way to limit an agent's shell to `git diff` (see Gotchas).

## Specifics

### Built-in and saved agents

| Agent | Purpose | Notes |
|---|---|---|
| `explore` | Fast read-only codebase search | Safe in parallel; uses a small, fast model by default |
| `task` | Runs tests, builds, linters | Brief summary on success, full output on failure |
| `general-purpose` | Full capabilities, separate context | Receives repository instructions |
| `code-review` | High signal-to-noise review of diffs | Never modifies files |
| `research` | Deep research | Only via `/research`, never auto-delegated |
| `rubber-duck` | Critique of plans, code, tests | Runs on a different model than the session; read-only |
| `security-review` | Exploitable vulnerabilities | `/security-review`; read-only |

Saved agents are `.agent.md` (or `.md`) files. The ID is the path under `agents/` without extension, with `/` replaced by `--`.

| Priority | Location |
|---|---|
| 1 | `~/.copilot/agents/` |
| 2 | `.github/agents/`, from the working directory up to the Git root (deepest wins) |
| 3 | `.claude/agents/` |
| 4 | `.github/agents/` under `--add-dir` roots |
| 5 | Plugin `agents/` |
| 6 | Organization or enterprise `/agents` in `.github` or `.github-private` |

### Definition fields

| Field | Meaning | Default |
|---|---|---|
| `description` | Required. Drives auto-delegation and the agent list | none |
| `name` | Display name; also usable with `--agent`. Not used for deduplication | the ID |
| `tools` | Tool names or aliases (`read`, `edit`, `search`, `execute`, `agent`, `web`, `todo`); MCP as `server/tool` or `server/*`; `[]` disables all | all (`["*"]`) |
| `model`, `models`, `modelPolicy` | One model, a priority list, and whether overrides are allowed (`preferred` or `required`) | inherits the outer model |
| `reasoningEffort` | Default effort | inherits |
| `disable-model-invocation` | `true` blocks auto-delegation (replaces `infer`, which the CLI reference still lists) | `false` |
| `user-invocable` | `false` hides it from manual selection | `true` |
| `include-custom-instructions` | Load repository instruction files when run as a subagent | `false` |
| `mcp-servers`, `metadata`, `target` | Extra MCP servers, annotations, `vscode` or `github-copilot` | none, none, both |

The prompt body is limited to 30,000 characters. Unrecognized tool names are ignored.

### What a subagent inherits

| | Behavior |
|---|---|
| Context | Its own window; the main conversation is not shared |
| Tools | All tools unless `tools` narrows them; MCP tools count too |
| Model | `model` if set, else the outer agent's. With session model `Auto`, subagents always inherit the resolved model |
| Instructions | `copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md` only with `include-custom-instructions: true`; `--no-custom-instructions` overrides it |
| Permissions | The `task` built-in runs with the parent's granted and denied permissions; the documentation doesn't specify this for custom agents |

If you select the agent yourself (`--agent`, `/agent`), it is the session agent and already follows repository instructions.

### Invocation, foreground and background

| How | Example |
|---|---|
| By description | The main agent picks the profile, unless `disable-model-invocation: true` |
| Slash command | `/agent`, choose `reviewer`, then enter a prompt |
| Mention | `Use the reviewer agent on this branch` (or `@reviewer` inside a `/fleet` prompt) |
| Command line | `copilot --agent reviewer -p "..."` (ID or quoted `name`) |
| Parallel | `/fleet PROMPT` or `--fleet` with `-i`/`-p`: an orchestrator splits work across subagents and may use matching custom agents |

Subagents can run in parallel where the work is independent. Ctrl+X then `b` promotes a running task to the background; `read_agent` and `write_agent` check on or message background agents, and pressing Esc twice while idle stops them. With `-p`, the CLI waits for background agents up to `COPILOT_TASK_WAIT_TIMEOUT_SECONDS` (default 600).

### Limits and cost

| Limit | Value |
|---|---|
| Nesting depth | 6 by default, max 256 |
| Concurrent subagents | By plan: 2 (Free), 4 (Pro), 8 (Max), 16 (Business), 32 (Enterprise) |
| Cost | Each subagent makes its own model calls and uses GitHub AI Credits; `/fleet` typically uses more |
| Fleet default model | A low-cost model, unless the profile sets `model` |

`/subagents` sets default and per-agent models for agents with `modelPolicy: "preferred"`.

## Gotchas

- `tools` has no documented syntax to allow only `git diff`. The `shell(git:*)` patterns belong to `--allow-tool` and `--deny-tool`, which apply to the session. Treat "read-only" as an instruction plus the missing `edit` tool, not as enforcement.
- The documentation doesn't confirm the MCP prefix for the CLI's built-in GitHub server in an agent's `tools`. The command reference names it `github-mcp-server`; the cloud agent page uses `github`. Unrecognized names are ignored, so a wrong prefix silently removes the tool.
- Without `include-custom-instructions: true`, a custom agent run as a subagent doesn't see your conventions, and the built-in `explore`, `task` and `code-review` never do.
- Setting `model` gives a second opinion only if it differs from the session model. `rubber-duck` picks a complementary model for you each time.
- User-level agents beat repository ones with the same ID, so a personal `reviewer.agent.md` silently shadows the team's.