Stop renting the built-in subagents — write your own in a Markdown file with frontmatter

A custom subagent is a Markdown file that defines a specialised assistant Claude can delegate to. We've spent the last three Mondays on the three Claude ships with — Explore to find, Plan to design, general-purpose to do — but the more durable move is authoring your own. You give it a name, a description of when to use it, an optional tool allowlist, and a system prompt; from then on Claude can route matching work to it automatically, and it runs in its own context window instead of crowding your main thread.

Why bother, when general-purpose already has every tool. Because a named subagent encodes a standing instruction you would otherwise retype every session. A reviewer that always checks the same three things, a migration agent that knows your schema conventions, a docs agent that writes in your house voice — each becomes a reusable, version-controlled artifact rather than a paragraph you paste into the prompt and hope you got right. The system prompt in the file body is the persistent brief; the description is what Claude reads to decide when to hand work over.

Where the file lives sets its scope. Drop it in .claude/agents/ inside a repo and it's project-scoped — committed, shared with the team, shadowing anything of the same name from your user directory. Drop it in ~/.claude/agents/ and it follows you across every project. The same file format works in both places, so a subagent that proves itself in one repo is one move away from being yours everywhere.

The frontmatter is small on purpose. Only name and description are required. Omit tools and the subagent inherits everything the parent thread can reach, including connected MCP servers — add the field only to restrict, which is exactly what you want for a read-only reviewer that should never write. An optional model (haiku, sonnet, opus) lets you send cheap mechanical work to a smaller model and keep the expensive one for reasoning. The body below the frontmatter is the system prompt, and it should be specific: name the files, the conventions, and the definition of done.

You don't have to write the YAML by hand. Run /agents for an interactive view that lists every subagent available to you — built-in, user, project, plugin — and walks you through creating a new one, including generating a first draft you then edit. It's the fastest way to see what's already in scope before you add to it, and to fix a subagent's tool access without hunting for the file.

The trap to avoid: a vague description. Automatic delegation is only as good as that one line — “helps with code” will either never fire or fire on everything. Write it like a routing rule: what the agent is for, and when Claude should reach for it (“Use proactively after any change to the auth module to review for security regressions”). If you want to force it regardless, just name the agent in your prompt. Get the description right and the delegation disappears into the background, which is the whole point.

The try-it block builds one project-scoped reviewer in under a minute.