skip to content

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?

level: juniorimportance: should knowfreq 10%

answer

  1. a Markdown file, not a setting
  2. a folder under .github in the workspace
  3. YAML frontmatter, then the instructions
  4. the tools list decides what it can touch
  5. formerly custom chat modes

basics

~10 s

A 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 s

In 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
markdown
---
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

for a junior

Recall the folder and the extension: .github/agents and .agent.md. Know that frontmatter configures the agent and the body is its instructions.

for a middle

Explain the main frontmatter fields, why an absent tools list means all tools, and how handoffs move the conversation to another agent.

for a senior

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.

for a principal

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.