Custom Subagents: Build Your Own

architecture

Custom Subagents: Build Your Own

Define specialized subagents with their own tools, prompts, and personalities. Examples for code-review, security audit, and design-blueprint roles.

Most Claude Code users treat every task the same: one model, one context window, one shot. Custom subagents break that pattern. They let you spin up isolated workers with their own model, tools, memory, and personality, then return only the result to your main session. The result: cheaper runs, cleaner context, and purpose-built intelligence for every sub-task.

This breakdown covers what a subagent actually is, how its definition file works, three production-ready examples, when spawning makes sense, and the pitfalls that trip people up the first time.

Subagent vs Agent vs Skill

These three words get mixed up constantly. Here is the precise distinction:

A Markdown file loaded into the current model's context. No separate process. No separate model. Just extra instructions and patterns your main session can read.

The interactive Claude Code process you talk to. It has full tool access, your project context, and carries the whole conversation history.

A separate Claude process spawned by your main agent. Runs in its own context window, uses its own model and tools, then returns only the result. Context stays isolated. No bleed.

Subagent definition file structure

A subagent is a single Markdown file placed in .claude/agents/. The frontmatter configures the worker; everything below the closing ---is its system prompt.

Identifier used when spawning or referencing the agent.

Claude reads this to auto-select the right agent. Be specific about when to use it.

Any Claude model. Haiku for cheap reads; Sonnet for reasoning; Opus for high-stakes output.

Limit tools to what the task actually needs. Read-only agents can never accidentally write or delete.

Skills to inject before the system prompt. Useful for domain knowledge.

Runs in an isolated context window. The only sane default; it prevents context bleed back to main.

3 worked example subagent definitions

Drop these into .claude/agents/ and they are immediately available.

Pull-request reviewer that checks for logic errors, unclear naming, and missing edge-case handling. Returns a bullet list, nothing more.

OWASP-focused auditor. Scans API routes, auth logic, and input handling. Only reads; it can never modify anything.

Reads existing component files and produces a structured design spec (layout, spacing, color tokens, and component hierarchy) ready for a rebuild or handoff.

When to spawn vs work directly

Spawning has overhead. Use it when one or more of these conditions apply:

• •Task is read-only research or audit; isolate it
• •You want a different model (Haiku for cheap scans)
• •The sub-task would bloat the main context by 5k+ tokens
• •Multiple sub-tasks can run in parallel
• •You need a specialist personality (security mindset, design eye)
• •Task needs the full conversation history to proceed
• •You need to write files; main session is safer
• •Sub-task is short (under 10 tool calls)
• •You need iterative back-and-forth with the user mid-task
• •Latency matters more than context cleanliness

Pitfalls

Claude decides which agent to call by reading the description field. If it says "helps with code" it will almost never trigger. Write it like a routing rule: "Use when reviewing a PR or analysing auth logic before merge."

Without fork, the subagent shares context with the parent. The whole point of a subagent is isolation. Always set context: fork unless you have a deliberate reason not to.

A security auditor with Write access is a liability. Explicitly restrict tools to ["Read", "Grep"] for any agent that doesn't need to modify files. The agent can't break what it can't touch.

Haiku is 10× cheaper than Sonnet and fast enough for search, summarise, classify, and extract. Reserve Sonnet for agents that write code or need multi-step reasoning.

Subagents run to completion and return a result. If you need to ask follow-up questions mid-task, stay in the main session. Spawning is fire-and-collect, not a dialogue.

Want this running in your stack?

ManasFlow builds agent systems, RAG pipelines, and Claude Code setups for production teams.

Claude Channels: Deep Dive

Persistent Memory: Claude That Remembers