Custom agents & subagents

In the last chapter you took a task your team does over and over — scaffold an audited endpoint our way — and froze it into a prompt file, so a single / invocation carries the steps instead of your memory. You even saw that a prompt file can be pinned to a particular agent. This chapter is about building that agent.

This is also where the careful half of the work begins. Act 1 opens, and Act 1 is the shared library. The approval feature can’t ship until shared-lib grows a new audit-event type and a threshold rule — and shared-lib is imported by roughly twelve services. A wrong move here doesn’t break your app; it breaks a dozen apps you’ve never opened. That’s the highest blast radius in the whole course, and it’s exactly the situation that justifies setting up real machinery before you touch a line.

Custom agents are not the built-in modes

You already know four ways Copilot can behave: Ask, Edit, Agent, and Plan. Those are the built-in modes — the levels of latitude you switch between with the dropdown. A custom agent is something you make yourself: a named, reusable persona, saved as a file in your repo, that bundles a job description, a scoped set of tools, and a set of conventions into one thing you can summon by name.

The difference that matters: a mode is how much freedom Copilot has right now. A custom agent is who Copilot is being — a reviewer that knows shared-lib’s compatibility rules, an investigator that only reads, a coordinator that delegates. You stop re-explaining “here’s how this library treats breaking changes” at the top of every session, because the agent carries that context for you. For a high-blast-radius repo where the rules are the whole point, that’s not a convenience. It’s the difference between a reviewer who knows the codebase and a stranger you brief from scratch every morning.

What this chapter builds

We’ll build the team you need to change shared-lib safely, then use it:

• Create a custom agent — the .agent.md file, where it lives, and the frontmatter that defines it — Create · .agent.md & /create-agent
• A reviewer for the shared library — a library-reviewer persona that holds the compatibility rules so you don’t have to — A reviewer · a persona for shared-lib
• Fan subagents out across the consumers — one coordinating agent delegating a breakage check to twelve isolated subagents — Subagents · fan out across consumers
• Handoffs and the plan agent — chaining agents into a sequence, and planning the library change before any code — Handoffs · chaining agents

By the end you’ll have a reusable reviewer that already knows the rules, and a way to check every consumer for breakage in parallel before you ship. Start with the file: create a custom agent.