Why your Copilot CLI custom agent isn't loading, and what it inherits

A custom agent in GitHub Copilot CLI is a Markdown file with YAML frontmatter — the settings block at the top — usually named something.agent.md. It defines a specialist role: a reviewer that can read but not edit, a test writer that follows one framework, a planner pinned to a model. When the main agent delegates work to it, the work runs in a subagent, a separate agent with its own context window (the fixed amount of text the model can consider at once).

Two failures hide behind "my agent isn't working". Either the file was never loaded, so it cannot be selected, or it loaded without the instructions, tools, or model you expected. An entry in the picker proves only the first.

Run copilot --version first. Discovery, the instruction opt-in, and the model fields all changed during 2026, and the fixes below name the release.

Checked against GitHub's Copilot CLI documentation on 27 October 2026.

Status, 27 October 2026: repository instructions became opt-in for a custom subagent in 1.0.86. The built-in explore, task and code-review agents still receive none (#1990, open), and a long session can lose a selected agent's own instructions at compaction, the step that replaces older turns with a summary (#2895, open).

Where Copilot CLI looks for agent files#

Six sources, highest priority first (CLI reference):

For user, project and added-root agents, the ID is the path. A file directly in an agents directory takes its filename without .md or .agent.md; in a subdirectory the separator becomes --, so agents/team/reviewer.agent.md is team--reviewer. That ID is what the CLI deduplicates on and one of the values --agent accepts. Plugin agents use their plugin namespace, for example plugin:agent, and remote agents use the ID their source defines.

A personal agent wins. Deduplication is by ID, so ~/.copilot/agents/reviewer.agent.md beats the repository's reviewer.agent.md. The name field does not deduplicate: two agents with the same name but different filenames both load, and an --agent value matching both takes the higher-priority one.

The project walk goes up, not down. Copilot checks the current directory, then each parent to the Git root. Start at the repository root and a package's .github/agents/ is not on the path, so its agents do not load; start inside the package and both load, with the package winning on an ID clash. Discovery from a subdirectory was fixed in 1.0.62; the --add-dir half of the same report was still failing on 1.0.82 and was closed as resolved in 1.0.89 (#3688, closed 30 September 2026).

An added directory contributes agents. From 1.0.89, Copilot loads .github/agents/ from a directory added with --add-dir or /add-dir at priority 4. Adding it is a trust decision.

Remote agents need a remote. Organization agents live in the agents directory of the organization's .github or .github-private repository; enterprise agents in the .github-private repository of a designated organization (location table). When the CLI cannot resolve them, /agent says so: an open report shows "could not load remote agents, no GitHub remote found" (#1285, open, updated 29 September 2026). Check the remote and your authentication before editing the profile, especially when the same agent works in VS Code.

Why it is not in the list#

If the picker says there are no custom agents, Copilot found none it could load.

• It is in ~/.claude/agents/. User-level Claude configuration stopped loading in 1.0.36: agents, skills, and commands in ~/.claude/ are ignored. Project .claude/agents/ still works at priority 3. Personal agents belong in ~/.copilot/agents/. This asymmetry catches people moving from Claude Code.
• The filename is a built-in name. An agent named explore, task, general-purpose, or code-review (the documented examples) loads but is never dispatched, with no warning (#1528, open, updated 6 April 2026). Rename it.
• It is not an agent file. Every Markdown file in the agents directory is parsed as an agent, so a guidance file at .github/agents/AGENTS.md fails with a frontmatter error (#4410, open, 8 August 2026). Instructions belong at the repository root or in .github/instructions/.
• The frontmatter is invalid. description is required. /agent lists failed agents with the parse error, and since 1.0.70 and 1.0.71 --agent reports the real error for a broken file.
• target: vscode does nothing. The shared reference documents it, but in the CLI the agent still appears and still runs (#4806, open, 10 September 2026).
• The tree is large. Discovery past 100 agents, or deeply nested, was fixed in 1.0.97; older builds miss some.
• It is a plugin agent. Plugin agents load at priority 5 when the plugin is installed and enabled; selection was fixed in 1.0.85 and --plugin-dir invocation in 1.0.97.
• You are looking for a built-in. /agent lists custom agents only, so a built-in's absence is by design.

There is no documented way to make a custom agent the default for every session. Select it with /agent, name it in the prompt, or pass --agent; a persistent default is an open request (#2212, open, 6 April 2026). A shell alias that passes --agent is the workaround.

What it inherits when it runs#

From the CLI reference. research, rubber-duck, and security-review are not in that table, so do not assume either answer for them.

The rule is deliberate: a subagent stays focused and cheap. When you pick the agent yourself it is the session agent, so it follows copilot-instructions.md, AGENTS.md, and CLAUDE.md already. When the main agent delegates, it does not.

If the agent reviews or edits code, opt in:

---
name: RepoAwareReviewer
description: Reviews a change against this repository's conventions
tools: ["read", "search", "edit"]
include-custom-instructions: true
---

Review the change and flag anything that violates the repository's conventions.

Three edges matter:

• include-custom-instructions only applies to the subagent case.
• A subagent with the flag reads the repository's own files, not extra instruction directories you loaded for the main session, such as one pointed at with COPILOT_CUSTOM_INSTRUCTIONS_DIRS.
• --no-custom-instructions beats the flag: with that option, no agent receives repository instructions.

The built-in gap is the one that surprises people. A rule like "never use system Python, use uv run" in AGENTS.md is followed by the main agent and general-purpose, and ignored by explore, task, and code-review (#1990). Put the rule in the agent's own body, or route that work through general-purpose.

The model it actually uses#

Four fields, documented in the CLI reference: model (one model; unset, it inherits the parent's), models (a priority list, first one your plan can access, overriding model), modelPolicy ("preferred" allows the subagents override or /subagents picker to change it; "required" refuses the dispatch rather than substitute), and reasoningEffort (how much internal reasoning the model is allowed to spend).

Resolution runs highest first: an explicit per-call value, the subagents override in ~/.copilot/settings.json, the agent definition, then the parent session. Effort follows the same chain.

Two behaviours explain most "wrong model" reports.

Auto ignores the field. When the session model is Auto, the server picks the model, and subagents always inherit that resolved session model regardless of their own model or models.

An unavailable model falls back, quietly. A declared model or effort that cannot be honoured falls back to the session's value rather than failing, unless the agent sets modelPolicy: "required". Reports describe the fallback as silent: a subagent requested on one model returns on another, visible only in the result metadata's model: line (#3266, open, 12 May 2026). A related request describes a cost guard that downgrades to the session model and logs it only in the process log (#2758, open, updated 26 May 2026). Set models in a realistic order, and require the model when substitution would invalidate the result.

/subagents (also /agents) shows and changes the effective model, reasoning effort, and context tier per agent, and locks the Model entry when the policy is required. --model sets the session model, which is the fallback when neither the agent definition nor a subagents override names one.

What the tool list really filters#

tools defaults to ["*"], every tool.

• A wildcard anywhere grants everything. ["view", "*"] is not "view plus defaults"; it grants every tool. Remove the * if you wanted a narrow agent.
• An empty list disables every tool. tools: [] gives an agent that can plan and talk but not act.
• Unknown names are ignored without an error. The aliases are execute, read, edit, search, agent, web, and todo, each accepting older names such as shell, Grep, Glob, and Task. MCP tools, exposed by an external MCP server, are named server/tool; server/* enables a whole server.

Check what loaded, without asking the model#

Asking the agent "which instructions do you have?" tests the model's self-description, not the CLI's state.

• /agent lists the custom agents it found, shows load failures with their parse errors, and lets you select one.
• /env shows the loaded environment: instructions, MCP servers, skills, agents, hooks, plugins, LSPs, and extensions.
• /subagents shows the model, effort, and context tier each agent will use.
• copilot --agent <id> --prompt "..." runs one agent for one prompt. The ID or the quoted name both work.
• The result metadata's model: line is where a silent substitution shows up.

There is no non-interactive agent list: the docs say custom agents need a live session and are not covered by copilot instruction, copilot lsp, copilot plugin, copilot mcp, or copilot skill.

Two session events change which agent is active. /clear and /new reset the selection (1.0.40); resuming restores the agent that was saved (1.0.12 and 1.0.19). After a long session, check the persona separately: an open report says compaction strips the selected agent's system-prompt block and does not restore it (#2895, open, 28 April 2026, reported on 1.0.34). Re-select the agent with /agent; if the behaviour does not return, start a new session and keep the role's rules in a file.

Where to go next#

• Why Copilot CLI ignores your AGENTS.md — when repository rules do not reach the agent.
• Why your Copilot CLI skill isn't being used — when the agent needs a skill it cannot find.
• Copilot CLI guides — the rest of the set.
• Context compaction — when a long session changes the agent's behaviour.