Custom agents & subagents

A prompt file captures a procedure. But some work needs a persona: a reviewer that holds a library’s compatibility rules, an investigator that only reads, a coordinator that delegates to other agents. Re-explaining “here is how this library treats breaking changes” at the top of every session is its own kind of repetition - the persona version of re-typing your conventions.

That is what a custom agent is: a named, reusable role you define yourself, saved as a file in your repo, bundling a job description, a scoped set of tools, and conventions into one thing you summon by name. And because a custom agent can be allowed to call other custom agents, you can build small teams - one coordinating agent fanning checks out to focused subagents.

This chapter builds the team you need for the riskiest shape of work in this course: a change to a shared library that other services import. In the running scenario that is shared-lib, imported by roughly a dozen services - a wrong move there does not break your app, it breaks apps you have never opened. That risk profile is exactly what justifies setting up real machinery before touching a line.

Custom agents are not the built-in roles

Copilot’s built-ins are Ask, Plan, and Agent in the agents dropdown - the role picker in the Chat view. A custom agent is an entry you add to that same dropdown. The difference that matters: a built-in role is how much freedom Copilot has right now; a custom agent is who Copilot is being - a reviewer that knows the compatibility rules, an investigator that cannot edit, a coordinator that delegates. For high-consequence work where the rules are the whole point, that is not a convenience. It is the difference between a reviewer who knows the codebase and a stranger you brief from scratch every morning.

What this chapter builds

The team for a safe shared-library change, then the workflow that uses it:

• Create · .agent.md & /create-agent - the file, where it lives, the frontmatter that defines it, and four ways to make one.
• A reviewer · a persona for shared-lib - a library-reviewer that holds the additive-only rule so you stop re-explaining it.
• Subagents · fan out across consumers - one coordinating agent delegating a breakage check to a checker per consumer.
• Handoffs · chaining agents - suggested next steps that move work down a plan-review-audit sequence.

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