How to Build Better Claude Code Subagents

TL;DR

Use Claude Code subagents to delegate isolated tasks while preserving the main session’s context. Give each custom agent precise YAML front matter, focused instructions, an appropriate model, and only the tools it needs. Strong descriptions improve automatic invocation, while parallel specialists can review work from distinct perspectives, perform research, search connected data, and report results to the orchestrating session.

Transcript

So, I don't know what's going on up here, but I just told Claude Code to spin up five different sub aents, and they all have different personalities. One is going to be a complete beginner, one will be a software engineer, one will be a business owner, one will be a publisher. And it comes back, and it says, "Okay, I'm kicking off all five now, eac... Read More

Key Insights

• A Claude Code subagent is a separate chat session that receives work from the main session and reports its results back. The main session acts as the orchestrator, communicates with the user, assigns tasks, and combines the returned findings into an overall response.
• Subagents preserve the main context by handling research, file reading, and other detailed work inside fresh conversations. This separation prevents supporting material and intermediate reasoning from filling the primary context window when the user still needs the main session for broader work.
• Parallel subagents can evaluate the same material through distinct personas and professional perspectives. The demonstration assigns reviews to a complete beginner, a software engineer, a business owner, a publisher, and an enterprise executive, then lets the main session produce an overall assessment.
• Built-in agents are generic Claude Code agents that can be invoked automatically or prompted with temporary roles. Giving a general-purpose agent a persona does not create a custom agent, even when that persona substantially changes the perspective used to complete its assigned task.
• A custom subagent is defined in a Markdown file with YAML front matter followed by detailed instructions. The front matter can specify the agent’s name, description, model, color, tool permissions, disallowed tools, MCP servers, and skills, while the body defines how the agent performs its work.
• Progressive disclosure works by letting Claude Code inspect only an agent’s name and description before deciding whether it applies. The full instructions are loaded only after selection, which avoids spending context tokens on every available agent when most are irrelevant to the current request.
• The description is the primary trigger for automatic agent selection. A precise description reduces misfires, while wording such as "use proactively" can encourage broader invocation. Reliable descriptions are developed through repeated use, observing failures to trigger and unwanted triggers, then refining the wording.
• Model selection can reduce the cost of delegated work because the main session and its subagents do not need to use the same model. The demonstration keeps the main session on Opus while assigning research to Haiku or Sonnet, preserving the orchestrator while using cheaper specialists.

Questions & Answers

Q: What is a Claude Code subagent?

A Claude Code subagent is a separate chat session that receives a specific assignment from the main session. The main session acts as an orchestrator, asking subagents to read files, research a subject, fix a bug, search connected data, or review content. Each subagent works in its own fresh context and returns a report to the main session, which then communicates the combined result to the user.

Q: How do Claude Code subagents keep the main context clean?

Claude Code subagents keep the main context clean by moving detailed supporting work into separate conversations. Research results, file contents, searches, and intermediate task information accumulate inside the subagent rather than the primary session. The subagent returns a focused report when finished, allowing the main session to preserve more of its context window for ongoing discussion, orchestration, and decisions that span the larger project.

Q: What is the difference between built-in and custom Claude Code agents?

Built-in agents are native, general-purpose agents that Claude Code may invoke automatically or prompt with a temporary persona and assignment. A custom agent is a Markdown file created with its own YAML front matter and working instructions. Assigning a software engineer or beginner persona to a general-purpose agent changes its prompt, but it does not create a reusable custom agent with a defined name, model, permissions, description, and behavior.

Q: How do you create a custom subagent in Claude Code?

Create a custom subagent as a Markdown file in the appropriate agents folder. Add YAML front matter at the top to define settings such as the agent’s name, description, model, color, tools, disallowed tools, MCP access, and skills. Below that configuration, write the instructions and steps the agent should follow. The completed file becomes a reusable specialist that Claude Code can select through natural-language requests.

Q: Why is the description important in a Claude Code subagent?

The description is important because it functions as the agent’s trigger. Claude Code reads the name and description to determine whether the custom agent applies to a user’s request before loading its complete instructions. A precise description makes automatic selection more reliable. A vague description can produce misfires, either failing to invoke the agent when needed or invoking it for requests that should use another approach.

Q: What is progressive disclosure in Claude Code agents?

Progressive disclosure is the process of inspecting a small amount of agent metadata before loading the complete agent definition. Claude Code initially reads the name and description in the YAML front matter to judge relevance. If the agent matches the request, Claude Code loads and runs the additional instructions. If it does not match, the system avoids reading everything, which prevents unnecessary consumption of context tokens.

Q: How can you improve automatic subagent invocation?

Improve automatic invocation by writing a narrow, precise description that clearly identifies the tasks the agent should handle. If broader automatic use is desirable, the description can include wording such as "use proactively." Then test the agent repeatedly in realistic conversations. When it fails to run, analyze why the description did not match. When it runs unnecessarily, tighten the trigger language and continue refining it through use.

Q: How can Claude Code subagents reduce model costs?

Claude Code subagents can reduce costs because the orchestrating session and delegated workers can use different models. The example keeps the main conversation on Opus while allowing research work to run on Haiku or Sonnet. This arrangement reserves the expensive model for user communication and coordination while cheaper agents handle isolated assignments. Each delegated task also receives a fresh context instead of expanding the main session with extensive research material.

Summary & Key Takeaways

• Claude Code subagents are separate sessions that receive delegated work from a main orchestrating session. They can run tasks such as reading files, conducting research, fixing bugs, searching connected data, or reviewing material from different perspectives. Their isolated contexts prevent task details from unnecessarily filling and polluting the main conversation’s context window.

• Claude Code provides built-in agents and supports custom agents stored as Markdown files. A custom agent includes YAML front matter for configuration and a body containing its working instructions. Important front matter fields include its name, description, model, color, permitted tools, disallowed tools, MCP access, and any skills it may invoke.

• Effective custom agents depend on precise descriptions and carefully written instructions. Claude Code reads an agent’s name and description before deciding whether the agent applies, a process described as progressive disclosure. Testing reveals invocation misfires, allowing descriptions to be refined until relevant requests reliably trigger the agent while unrelated requests do not.