How to build Claude subagents better than almost everyone

Most people use Claude Code as a single all-purpose assistant. That works, but it barely scratches what the tool can actually do. The real power comes when you start delegating work to subagents: small, specialized Claude sessions that run in parallel with their own context, tools, and even models.

Used well, subagents give you cleaner chats, cheaper workloads, and much better results on complex tasks. This guide walks through what they are, how they work inside Claude Code, and how to design subagents that are better than what 99% of users ever build.

What Claude subagents actually are

In Claude Code, your main chat is the orchestrator. It’s the session you type into. From there, you can spin up subagents: separate Claude sessions with their own instructions, tools, and memory.

Each subagent:

• Has a fresh context window (no history from your main chat)
• Can use a different model (Opus, Sonnet, Haiku, etc.)
• Can have its own persona and role (beginner, CTO, researcher, critic, etc.)
• Runs in parallel with other subagents and reports back to the main session

Think of the main chat as the manager and subagents as specialized team members. The manager delegates work, the subagents do the job, and then the manager summarizes or combines their results for you.

Why subagents are so useful

Subagents exist for a few core reasons that become obvious once you start using them regularly.

1. They keep your context clean

Long Claude Code sessions quickly fill up with research, drafts, logs, and side conversations. That bloats the context window and makes the model less precise over time.

When you delegate a task to a subagent, it runs in a completely fresh chat. All the messy research, long documents, or intermediate steps live in that subagent’s context, not in your main one. Your primary session stays focused on the high-level conversation and decisions.

2. They let you mix models and save money

Your main session might be running on Opus, which is powerful but expensive. Many tasks don’t need that level of intelligence. With subagents, you can:

• Keep your main chat on Opus for strategy and orchestration
• Delegate heavy reading, basic research, or routine analysis to Haiku or Sonnet
• Only send back a short summary or conclusion to the main session

Example: instead of having Opus read a 300-page report, you spin up a Haiku subagent to read it, extract key points, and return a tight summary. You get 90% of the value at a fraction of the cost.

3. They create true specialists

It’s tempting to treat AI as one mega-assistant that does everything. In practice, you get better results when each agent is a specialist with a narrow, well-defined job.

Subagents are perfect for that. You can create agents like:

• Security auditor for code and infrastructure
• Test writer that focuses only on unit and integration tests
• Documentation writer that turns code into clean docs
• Database architect that designs schemas and complex queries
• Harsh critic that roasts your business plans and product ideas

Each subagent can have its own persona, instructions, tools, and memory, so it behaves like a real expert in that area.

Built-in vs custom subagents

Claude Code already uses subagents under the hood. For example, when it spins up a researcher to browse the web, that’s a built-in subagent. You’ll sometimes see these get invoked automatically when you ask for research-heavy tasks.

On top of that, you can create your own custom subagents. These live as markdown files in your .claude directory and are fully configurable: model, tools, memory, description, and behavior.

Where subagents live in your .claude folder

Claude Code stores configuration in a .claude folder, both at the project level and the global (user) level. Subagents are just markdown files in an agents folder.

Typical structure:

• .claude/agents/ – subagent definitions
• .claude/skills/ – skill definitions (very similar to subagents)
• Other config files, hooks, and MCP server settings

Because subagents are just markdown files, you can:

• Move them between projects
• Share them with teammates by committing them to a repo
• Copy them from public GitHub repos into your own setup

Front matter: the key to smart subagents

Every subagent file has two main parts:

1. YAML front matter at the top (between --- lines)
2. The body instructions below

The YAML front matter is crucial. It tells Claude Code:

• The agent’s name (how it’s referenced)
• A short description (when it should be used)
• The model to run (Opus, Sonnet, Haiku, or inherit from parent)
• Which tools and MCP servers it can or cannot use
• Whether it has memory (project, user, local, or none)
• Optional visual details like color in the UI

Claude uses a pattern called “progressive disclosure.” It first scans only the front matter (especially the description) to decide whether a subagent might be relevant. If it decides to use it, then it loads the full body of the file.

That’s why the description is so important: it’s effectively the trigger rule for when your subagent gets invoked automatically.

Designing great subagent descriptions

A weak description means your subagent either never fires when it should or fires when it shouldn’t. To avoid that, you want descriptions that are:

• Precise about the job: what this agent does and what it doesn’t
• Clear about triggers: phrases or situations where it should be used
• Short enough to be unambiguous, not a wall of text

You can even explicitly say things like “use proactively” if you want Claude to invoke it generously whenever the situation matches.

In practice, you’ll need to iterate. When a subagent doesn’t fire where you expected, or fires when you didn’t want it to, ask Claude Code why. Have it compare your prompt to the agent’s description and suggest edits. Over time, you tune the description until misfires are rare.

Subagents vs skills: what’s the difference?

Subagents and skills look very similar: both are markdown files with front matter and instructions. Both can define tools, models, and workflows. Both can call each other (skills can invoke subagents and vice versa).

The main practical differences are:

• Context window: Subagents run in their own clean session; skills usually operate inside your main chat’s context.
• Parallelism: You can run many subagents in parallel, each with its own context; skills are typically invoked inline in the current conversation.
• Usage pattern: Skills feel like functions you call; subagents feel like separate workers you delegate to.

In other words, use a skill when you want a reusable behavior inside the current chat, and use a subagent when you want a separate, parallel worker with its own context and possibly a different model.

Project-level vs global subagents

Claude Code supports two scopes for subagents:

• Project-level: Subagents stored in the .claude folder inside a specific repo. They travel with that project if you share the repo.
• Global (personal): Subagents stored in your user-level .claude directory. They’re available in any project on your machine but are not shared when you share a repo.

Use project-level agents for workflows tightly tied to that codebase or product. Use global agents for personal utilities you want everywhere, like a generic “plan roaster” or “meeting summarizer.”

Creating subagents from the Claude Code UI

You don’t have to handwrite every markdown file. Claude Code includes a simple UI flow to generate subagents:

1. Use the /agents command to open the agents panel.
2. Choose to create a new agent and select its scope: personal/global or project.
3. Pick “generate with Claude” or “manual configuration.”
4. Describe what the agent should do and when it should be used, as clearly and comprehensively as you can.
5. Choose allowed tools (for example, read-only only), model (Haiku, Sonnet, etc.), color, and memory scope (project, user, local, or none).
6. Save the agent, then open the generated markdown file and trim the description down to something concise and precise.

Claude will often generate a very long description by default. That’s fine as a starting point, but you’ll usually want to shorten it so the trigger logic stays sharp and unambiguous.

Safety and permissions for subagents

Because subagents can use tools and MCP servers, you should treat them like real processes with real access. Don’t rely only on “please don’t do X” in the prompt. Use explicit permissions.

In the front matter, you can:

• Allow or disallow specific tools (for example, read-only file access only)
• Restrict which MCP servers the agent can call
• Prevent it from writing or editing files entirely

A good mental model: if an agent can see or touch data, assume it eventually will. Use tool restrictions and MCP whitelists to enforce hard boundaries, especially for agents that work with sensitive code or data.

Using cheaper subagents as “workers”

One of the most effective patterns is to treat your main Opus session as the “smart boss” and your subagents as cheaper workers.

Example setup:

• Main chat: Opus, responsible for planning, orchestration, and final decisions.
• Subagents: Haiku or Sonnet, responsible for reading long documents, scanning codebases, doing repetitive research, or generating first drafts.

The workflow looks like this:

1. You ask the main chat for a complex outcome (e.g., “analyze these 10 documents and propose a strategy”).
2. The main chat spins up multiple Haiku subagents to read and summarize each document in parallel.
3. Each subagent reports back a short summary or structured data.
4. The main Opus session synthesizes everything and gives you a high-quality final answer.

This pattern keeps your costs down while still using the strongest model where it matters most.

When you should (and shouldn’t) use a subagent

Subagents are powerful, but you don’t want to use them for everything. Here are some practical signals.

Good times to use a subagent

Consider delegating to a subagent when:

• You’re about to read a lot of files or a huge document.
• The output will be a giant wall of text you’ll rarely revisit.
• The job is repeatable and deserves its own reusable workflow.
• Tasks are independent and can run in parallel (e.g., each chapter of a book can be reviewed separately).
• You want an unbiased or “fresh” reviewer with no prior context or memory.

Times to stay in the main chat

You probably don’t need a subagent when:

• It’s a quick, one-off edit or small question.
• Each step depends heavily on the last (1 → 2 → 3 → 4) and needs a shared conversation history.
• The agent needs to ask you follow-up questions mid-task.
• You need multiple agents to talk directly to each other and share a task list (that’s more of an agent team or orchestration problem).

Subagents have a one-to-one relationship with the main session. They don’t talk to each other directly. If you need complex multi-agent collaboration, you’ll want a different orchestration pattern, like the kind used in more advanced co-work setups or agent teams. For more on that style of automation, see this full tutorial on automating work with Claude Co-work.

Dynamic workflows and large subagent swarms

With newer versions of Opus, Claude introduced dynamic workflows: automatic, large-scale orchestration where the model spins up many subagents in parallel to tackle a big project.

In practice, this can mean:

• Dozens of subagents (40+, even 200+) running at once
• Massive parallelization on research, code analysis, or content generation
• Very fast progress—but also very high token and session usage

Because of how expensive this can get, Claude now uses a more specific trigger phrase for dynamic workflows (such as “ultra code”) instead of generic “workflow” wording. You can still ask for workflows explicitly, but you should be intentional: big workflows can burn through your session limits quickly.

Borrowing subagents from the community

You don’t have to build every subagent from scratch. Many developers publish their own agents in public GitHub repos, often grouped by specialty: API design, backend architecture, SQL, GraphQL, CLI tools, and more.

Because subagents are just markdown, you can:

• Copy a file from a repo into your .claude/agents folder
• Adjust the model, tools, and description to fit your environment
• Immediately benefit from someone else’s subject matter expertise

Just be cautious: review any third-party subagent for prompt injections or malicious instructions, especially if it has write access or powerful tools. You can even create a read-only “verifier” subagent whose only job is to inspect open-source agent files for suspicious behavior.

If you’re interested in leveling up your overall Claude setup, it also helps to understand how Claude Co-work and multi-agent workflows fit together. For that, check out this guide to using Claude Co-work better than almost everyone.

Putting it all together

Subagents are one of the most powerful features in Claude Code when you use them deliberately:

• Treat your main chat as the orchestrator and your subagents as specialists.
• Use project-level agents for repo-specific workflows and global agents for personal utilities.
• Keep descriptions tight and precise so progressive disclosure works in your favor.
• Use cheaper models like Haiku for heavy lifting and reserve Opus for strategy and synthesis.
• Add hard permission boundaries with tools and MCP restrictions, especially for sensitive data.

If you’re about to dump a pile of information into your chat that you’ll never read again, that’s usually a sign you should spin up a subagent instead. Once you start thinking this way, Claude Code stops being just a chat window and starts feeling like a real team of AI specialists working under one smart lead.