Create a custom agent

Before you can build a reviewer for shared-lib, you need to know the shape of the thing you’re building. 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

Custom agents are .agent.md files in your repo’s .github/agents/ directory. Drop a file named library-reviewer.agent.md there and Copilot picks it up as an agent you can summon. If you keep agents somewhere else — or want a personal set outside any repo — the chat.agentFilesLocations setting tells Copilot where else to look.

Renamed from chat modes

If you’ve seen .chatmode.md files or docs referring to “custom chat modes,” that’s the old name. Custom chat modes were renamed to custom agents, and the file extension changed to .agent.md. The concept is the same; only the name moved. Use .agent.md — that’s the one thing in this chapter 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’ll 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 who’s choosing between agents.
• name — the agent’s display name in the dropdown and when you invoke it.
• tools — an array of tool and MCP names 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.
• model — which model the agent prefers. It takes either a single model name or a prioritized array, so you can express a fallback order. (We won’t pick a model here — that’s a later chapter, and the names churn. The mechanism is what matters: one name, or a list tried in order.)
• agents — the subagents this agent is allowed to call. List them by name, or use * to allow all of them. This is the field that turns a solo agent into a coordinator — you’ll lean on it heavily two lessons from now.
• handoffs — agents this one can hand off to as a sequential workflow, so finishing one stage transitions to the next.
• user-invocable — a boolean, defaulting to true, that controls whether you can summon the 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 for attaching hooks to the agent’s lifecycle.

You won’t fill in every field for every agent. A focused reviewer might set only description, name, and tools. A coordinator adds agents. The point is that each field maps to a decision you’d otherwise have to make — and re-explain — in chat.

Four ways to make one

You don’t have to author the file by hand from a blank buffer. There are four routes, and they suit different moods:

1. The agents dropdown in the Chat view — the same place you switch modes lets you create a new custom agent.
2. /agents — type it in chat to manage and create agents.
3. Command Palette → “Chat: New Custom Agent” — the menu route, which scaffolds the file for you.
4. /create-agent — a conversational generator. You describe the persona you want in plain language and it writes the .agent.md for you, frontmatter and all.

For your first agent, /create-agent is the gentle on-ramp: describe the reviewer you want and let it draft the file, then read what it produced and tighten it. That’s exactly what we’ll do next — except the persona we describe is a specific one, with rules that protect twelve consumers. Next: a reviewer for the shared library.