Your team wants one shared code-review persona in Copilot's VS Code agent picker — where does its custom agent file live, and what goes in it?
answer
- a Markdown file, not a setting
- a folder under .github in the workspace
- YAML frontmatter, then the instructions
- the tools list decides what it can touch
- formerly custom chat modes
basics
~10 sA shared custom agent is a .agent.md file committed to the repository's .github/agents folder: YAML frontmatter sets its name, description, tools and optional model, and the Markdown body holds the reviewer's instructions.
solid answer
~40 sIn VS Code, Copilot custom agents are Markdown files with the `.agent.md` extension. A workspace agent lives in `.github/agents`, so committing `.github/agents/reviewer.agent.md` gives every teammate the same entry in the **Agent** dropdown; personal agents live at user level, for example in `~/.copilot/agents`. The optional YAML frontmatter sets `name` (the file name if omitted), `description`, `tools`, `model` and `handoffs`; the Markdown body is the instruction text, prepended to the prompt whenever the agent is selected. For a reviewer, list only read and search tools — leaving `tools` out enables every available tool, not none. Custom agents were previously called custom chat modes; an old `.chatmode.md` file is renamed to `.agent.md` and moved into a supported folder.
code
markdown · 14 lines---
name: Reviewer
description: Review the current changes against our conventions without editing files
tools: ['search', 'read', 'web/fetch']
handoffs:
- label: Fix findings
agent: agent
prompt: Fix the issues listed in the review above.
send: false
---
You are the code reviewer for this repository.
- Review the changed files for correctness, error handling and missing tests.
- Report each finding with the file, the line and a suggested fix.
- Do not edit files or run commands.go deeper
Recall the folder and the extension: .github/agents and .agent.md. Know that frontmatter configures the agent and the body is its instructions.
Explain the main frontmatter fields, why an absent tools list means all tools, and how handoffs move the conversation to another agent.
Show you would review a shared agent's tool list like a permission change, and diagnose a missing agent through its location, user-invocable and the Diagnostics view.
Weigh workspace agents against organization-level agents: per-repository control and review against one definition maintained centrally for every repository.
## What a custom agent is In VS Code, the agent picker in the chat input offers **built-in agent roles** — **Agent** for implementation, **Plan** for researching an approach, and **Ask** for questions where the session target provides it. A **custom agent** adds your own role to that picker: a reusable bundle of instructions, a tool selection and, optionally, a preferred model. Instead of pasting the same review checklist into every conversation and re-selecting tools by hand, a developer picks *Reviewer* from the dropdown and the configuration comes with it. Custom agents are plain files, not settings. That matters for a team: the file is versioned with the code, reviewed in pull requests like any other change, and arrives on every clone. ## Where the file lives | Scope | Location | Who gets it | |---|---|---| | Workspace | `.github/agents/` in the repository | Everyone who opens the repository | | User | a home folder such as `~/.copilot/agents` | Only you, across workspaces | | Organization | defined on GitHub for the organization | Members, once `github.copilot.chat.organizationCustomAgents.enabled` is `true` | For the shared reviewer, the workspace scope is the answer: commit `.github/agents/reviewer.agent.md`. VS Code treats any `.md` file in `.github/agents` as a custom agent, but `.agent.md` is the documented extension and keeps the file recognisable. You can create the file by hand, with the **Chat: New Custom Agent** command, or from the Agent Customizations editor (Preview), which can also generate a draft from a description that you then review. ## What goes in the file The file has two parts. 1. **Optional YAML frontmatter** between `---` lines, which configures the agent. 2. **A Markdown body**, which is the agent's instructions. When you select the agent in the Chat view, the body is prepended to your prompt. The frontmatter fields a team uses most: - **`name`** — the label in the dropdown; the file name is used if it is missing. - **`description`** — shown as placeholder text in the chat input. - **`tools`** — a list of tool or tool-set names, including MCP tools (`<server name>/*` takes all of one server's tools). A tool that is not available in the session is ignored. - **`model`** — one model name, or a prioritized list tried in order; without it the model picker's current choice is used. - **`handoffs`** — buttons that appear after a response and switch to another agent with a pre-filled prompt (`label`, `agent`, `prompt`, optional `send`). - **`user-invocable`** and **`disable-model-invocation`** — whether the agent shows in the dropdown, and whether other agents may call it as a subagent. The older `infer` field is deprecated in favour of these two. The body can link other files with Markdown links or `#file:` references, so a reviewer can point at the team's existing guidelines instead of copying them. ## A reviewer that cannot edit The point of a reviewer persona is that it reports instead of changing code, and the `tools` list is how you get that. Give it the `search` and `read` tool sets (and perhaps `web/fetch`), and leave out `edit` and `execute`. Two details are easy to get backwards: - **Omitting `tools` does not make an agent read-only.** GitHub's reference for agent profiles says an absent `tools` property enables all available tools; an empty list `[]` disables them all. - **Listing a tool does not approve it.** Tool availability and tool approval are separate controls. A listed tool still runs under the session's permission level and approval settings. A `handoffs` entry pointing at the built-in `agent` gives the reviewer a one-click path back to implementation once the findings have been read, without granting the reviewer itself any editing tool. ## History and troubleshooting Custom agents **were previously known as custom chat modes**; the feature was renamed, not replaced. Existing `.chatmode.md` files are renamed to `.agent.md` and placed in a supported location. When a teammate says the agent does not appear: - Check that the file sits in a supported location for the harness they selected in the **Session Target** control. - Check that `user-invocable` is not `false`, which hides the agent from the picker while keeping it callable as a subagent. - Open **Configure Custom Agents** from the agents dropdown and hover an entry to see where it was loaded from, or right-click in the Chat view and choose **Diagnostics** to list every loaded agent and any parse error. Because the file is shared, editing it changes the agent for everyone who pulls the change — treat edits to its tool list with the same care as a change to CI permissions.
- A teammate cannot find the Reviewer agent in Copilot's agent dropdown in VS Code. What do you check first?Confirm the file is in `.github/agents` (a supported location for the harness selected in **Session Target**) and that its frontmatter does not set `user-invocable: false`, which hides it from the picker. Then hover the entry under **Configure Custom Agents** to see which file loaded, or open **Diagnostics** from the Chat view's context menu to see loaded agents and parse errors.
- Does narrowing `tools` in a Copilot custom agent remove the need for approval prompts?No. The `tools` list decides which tools the agent may use at all; approval decides whether a call runs without asking. A listed tool still goes through the session's permission level and approval settings, so a reviewer with `search` and `read` is limited by its list, not pre-approved by it.
- How do you keep a helper custom agent callable as a subagent but out of the dropdown?Set `user-invocable: false` in its frontmatter. Whether other agents may invoke it is controlled separately by `disable-model-invocation`. The old `infer` field, which mixed both, is deprecated.
- Copilot custom agents are configured in settings.json rather than in files.
- Leaving the tools property out makes a custom agent read-only.
- Listing a tool in the agent file auto-approves calls to it.
- Custom agents are a new feature unrelated to the old custom chat modes.
- The Markdown body is decoration; only the frontmatter changes behaviour.