How to Build Claude Code Subagents Better Than 99% of People

Claude Code shipped a way to delegate any job to a fresh, separate worker that carries nothing from your current session, costs less to run, and returns only the summary your main session needs to keep going cleanly. The feature is called subagents, and the reason most people have not used it is that it sounds more complicated than it is. A subagent is just a markdown file with a short header and some instructions, the same shape as any other skill file. The complexity is minimal. The benefit is real.

I am Madhuranjan Kumar. The mental model is a manager with a team. Your main chat is the orchestrator. Its job is to think, delegate, and relay results back to you. Subagents are the workers it delegates to, each running in a completely fresh context window with no memory of what your main session has been doing. That clean context is the entire point, and it is what most people miss when they use Claude Code for everything through a single long session.

A subagent is a markdown file, and that simplicity is the whole point

The format is intentionally minimal. A subagent file contains a short YAML header with a name and a description, followed by instructions telling the worker what it does and how to do it. That is the whole thing. No special syntax, no new programming language, no interface to learn. Because it is just a file, you can share it by dropping it in a folder, version-control it like any other piece of code, and move it between scopes by moving the file.

This simplicity is a design choice, not an oversight. A subagent that is hard to write and maintain would not get written and maintained. A subagent that is a markdown file is something a team can build, iterate on, and hand around without friction. Open repositories of ready-made subagents already exist with API designers, security auditors, and language specialists that others have already built. Because they are markdown, you can read exactly what instructions they contain before you trust them, which is the right habit before running any externally sourced code.

The description is the trigger, and a vague description misfires

The most important single line in any subagent file is the description in the header. Claude Code decides whether to invoke a subagent by reading only the name and description, not the full instruction body. That means the description is the trigger for the whole workflow. A precise description produces the right invocations. A vague description produces misfires where the subagent runs when it should not or fails to run when it should.

The calibration is fast once you know the loop. Write the description, watch whether it fires correctly on the first few relevant requests, and tighten the description wherever it misses. The description should say exactly what the subagent does and exactly when it should be used, written clearly enough that a reader could predict from the description alone whether this agent is right for a given task. When a subagent fires on the wrong kind of request, the description was too broad. When it fails to fire on the right kind, it was too narrow or did not match the language the main session used.

Fresh context is not a side effect but the main benefit

The feature that makes subagents worth setting up is fresh context, and it operates in two directions. First, it keeps your main session clean. As you work in a long Claude Code session, the context window fills with information you generated hours ago that you will never look at again but that the model has to read every time it responds. Delegating a heavy job to a subagent runs it in a fresh window. In one documented example, a reviewer subagent consumed roughly twenty-three thousand tokens of work and returned only a short summary to the main session, which stayed clean and responsive.

Second, it enables model cost optimization. The main session can run on the strongest model while subagents doing research, summarization, or routine checking run on a cheaper, faster model. The result is the full quality of the strong model on the decisions that matter, and the cost of a cheap model on the bulk work. For an agency or any team billing by output, cleaner context plus cheaper models on grunt work is a direct margin improvement that requires no change to the output quality the client sees.

For anyone running content production at volume, the parallel to routing in SEO content work is direct. You do not use the same resource allocation for generating a primary keyword article as you do for a meta description. You route each task to the appropriate level of effort. Subagents enable the same routing inside a Claude Code workflow.

Restricting tools at creation time beats restricting them with prompts

A subagent's tool access is set when the file is created, not in the prompt at runtime. This distinction matters because a polite instruction in a prompt is not a real constraint. A tool restriction in the file header is. Assume that if an agent can read data, it will, regardless of what the prompt says. If you want a reviewer to check code without ever being able to change it, restrict its tools so it cannot write or edit files at all. That restriction is enforced by the runtime, not by the agent's interpretation of your instructions.

The same logic applies to MCP server access. A subagent that only needs to read files should have no access to any server that can write or modify external systems. Building the restriction into the file at creation time is the habit that prevents a future session from accidentally triggering a write operation through a subagent you thought was read-only.

This is a concrete and underrated benefit of the subagent design. Because the tool list is in the markdown file, it is visible, auditable, and version-controlled. You can read exactly what tools any given subagent has access to before it runs. That is a cleaner security posture than runtime prompting, where the constraint lives only in the model's interpretation of your instructions.

Running independent jobs in parallel is where the real speed comes from

Subagents do not talk to each other. That constraint is also a feature. Because each subagent runs in a fresh context with no awareness of the others, independent jobs can run in parallel without any coordination overhead or context contamination. Reviewing fifteen documents at once, drafting five ad variations simultaneously, running three research passes on different topics in the same session, all of these are parallel jobs that a set of subagents handles faster than a single session working through them sequentially.

The right frame for deciding when to use a subagent is a short list of conditions: the work is about to dump output you will never reread, the job needs to read many files, the task repeats often enough to make a template worth building, or you want an unbiased reviewer who knows nothing about the conversation that produced the thing being reviewed. Skip subagents for quick edits, for steps that depend on each other sequentially, or when the worker genuinely needs the full conversation context to do the job correctly.

For a marketing team building Facebook and Instagram ad campaigns, the parallel-review use case is immediately applicable. Ten ad variations can go to ten reviewer subagents simultaneously, each checking the variation against the brief independently, and the main session receives ten summaries it can synthesize into a decision. The review that would have taken an hour of sequential checking happens in minutes. For any team billing by hours delivered on that kind of output, that is a measurable improvement in how many campaigns can be handled in a day.

The dynamic workflow capability, where the main session fans out tens to hundreds of parallel subagents in a single run, extends this further. It is powerful and it burns session limits fast, so it is worth using deliberately on genuinely large jobs rather than by default. But the simpler pattern, a handful of subagents running independent tasks in parallel, is immediately useful for almost any knowledge work that currently runs through a single long Claude Code session.