Create a custom agent

A custom agent is just a Markdown file. The body is the persona’s instructions - plain prose telling it who it is and how to work - and the frontmatter is the configuration that gives it tools, a model preference, and the right to call other agents.

Where the file lives

Workspace custom agents are .agent.md files in your repo’s .github/agents/ directory, or equally in .claude/agents/ - both are documented workspace locations. Drop a file named library-reviewer.agent.md in either and Copilot picks it up as an agent you can summon. For a personal set that follows you across repos, the user-level locations are ~/.copilot/agents/ and ~/.claude/agents/. (The chat.agentFilesLocations setting can still point VS Code at extra directories and is not deprecated, but GitHub Copilot CLI and the GitHub Copilot app do not inherit editor settings, so prefer the native folders above; the older chat.modeFilesLocations is deprecated.) Locations, the rename, the field list, and the current tool identifiers are per the VS Code custom agents documentation, verified October 2026 - if a tool name in an example below is ever rejected, that page and the tool list it links are the source of truth.

Renamed from chat modes

If you have seen .chatmode.md files or docs referring to “custom chat modes,” that is the old name. Custom chat modes were renamed to custom agents, and the extension changed to .agent.md. The concept is the same; only the name moved. Use .agent.md - that is the detail most likely to bite you if you follow an older guide.

What the frontmatter controls

The YAML frontmatter is where a custom agent stops being a note-to-self and becomes a configured persona. The fields you will reach for:

• description - what this agent is for, in one line. This is also how Copilot decides when the agent is a good fit, so write it for a reader choosing between agents.
• name - the display name in the dropdown and when you invoke it.
• tools - an array of tool and tool-set names (and MCP servers, via "<server>/*") the agent is allowed to use. This is how you scope an agent: a read-only investigator gets a narrow list; a builder gets more. Leaving something off the list is how you keep an agent from doing it - and when a prompt file pinned to an agent also declares a tools set, the prompt’s list wins for that invocation.
• model - which model the agent prefers: a single name or a prioritized array expressing a fallback order. The names churn with the product, so the mechanism matters more than any specific string; the Models chapter covers choosing.
• agents - the subagents this agent may call. List them by name, use * to allow all, or [] to allow none - and note the agent tool must also be in tools for delegation to work (the subagents lesson covers the pair). This is the field that turns a solo agent into a coordinator.
• handoffs - suggested next steps this agent offers: after it answers, it can render buttons that hand the conversation to the next agent (the GitHub.com cloud agent - Copilot working on GitHub rather than in your editor - does not support this property). Covered in the handoffs lesson.
• user-invocable - a boolean, defaulting to true, controlling whether you can summon this agent directly. Set it false for an agent meant only to be called by another agent, never picked from the dropdown.
• hooks - a preview field that runs automatic actions at the agent’s lifecycle points, such as before a tool runs.

You will not fill in every field for every agent. A focused reviewer might set only description, name, and tools. A coordinator adds agents. Each field maps to a decision you would otherwise make - and re-explain - in chat.

The next lesson shows a complete file: a library-reviewer that sets only name, description, and a read-only tools list.

Four ways to make one

You do not have to author the file from a blank buffer:

1. The agents dropdown - the Chat view’s role picker (Ask, Plan, and Agent) - can create a new custom agent.
2. /agents - typed in chat, to manage and create agents.
3. Command Palette, “Chat: New Custom Agent” - the menu route, which scaffolds the file.
4. /create-agent - a conversational generator: describe the persona in plain language and it writes the .agent.md, frontmatter and all.

Try it

Create a .agent.md for a code reviewer in your repo and scope its tools to read-only - the read and search tool sets. Ask it to review a recent change you made. Notice how the persona shapes the response: it should judge, not rewrite, and it should never offer to edit a file, because you did not give it the tool to.

For a first agent, /create-agent is the gentle on-ramp: describe the reviewer, read what it produced, tighten it. That is exactly what the next lesson does - with a persona whose rules protect a dozen consumers. Next: a reviewer for the shared library.