Claude Code Agents and Sub-Agents: The Complete Guide

Introduction

If you’ve been using Claude Code for more than a week, you’ve probably noticed that the model often spawns mysterious helper instances—tasks labelled Explore, Plan, or General Purpose—that go off, do something, and come back with a tidy summary. Those are sub-agents, and they’re one of the most under-rated features of the Claude Code ecosystem.

This article unpacks what agents and sub-agents are inside Claude Code, why you should care, how to use the built-in ones, and—most importantly—how to build your own custom agent from scratch with its own tools, memory, and system prompt. By the end, you’ll have a clear mental model and a working “code improvement advisor” agent in your own project.

📚 Table of contents

🤖 What is an agent (and a sub-agent) in Claude Code?

A sub-agent in Claude Code is a separate Claude instance, spawned via the Agent tool, that handles a focused task in its own context window and returns a single summary back to the main conversation. Think of it as delegating to a co-worker: they don’t see your full conversation history, they only get the prompt you hand them, and they hand back a result.

In the official terminology, “agent” and “sub-agent” are used interchangeably. Whenever the main Claude session delegates work, that delegated worker is a sub-agent.

🎯 Why sub-agents matter

👉 The biggest practical win is context. If you’ve ever had Claude Code start forgetting earlier instructions halfway through a long session, you were almost certainly past the point where a sub-agent should have absorbed the noisy work.

🧰 The built-in agents shipped with Claude Code

Claude Code ships with a handful of agents out of the box. You can see them in the agent picker (Shift+Tab in the CLI) and the model selects between them automatically based on your prompt.

Plan mode deserves special mention. When you toggle plan mode (Shift+Tab in the CLI), Claude Code runs the Plan agent in the background to assemble a plan before answering. It’s a sub-agent invocation under a different name.

🚫 When NOT to spawn a sub-agent

Sub-agents are not free. Every spawn starts cold—it re-derives context you already have—and burns tokens. Skip them when:

👉 Rule of thumb: if you can describe the task to a competent intern in two sentences and you don’t need to peek at their work, a sub-agent is appropriate. Otherwise, do it inline.

🔗 How agents compare to LangChain “create agent”

If you’ve built agents with LangChain’s create_agent or LangGraph, Claude Code sub-agents will feel familiar. Both share the same core idea: spawn an independent LLM instance with a constrained toolset and a system prompt, hand it a task, get a result back.

Treat Claude Code sub-agents as the productised, developer-friendly version of the same idea. If you already understand the LangChain pattern, you understand this—just expressed as a Markdown file.

🛠️ Creating a custom agent: step-by-step

Let’s walk through building a Code Improvement Advisor—an agent that scans your project and suggests readability, performance, and best-practice improvements without touching the code.

Code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

🧬 The anatomy of an agent .md file

Every Claude Code agent is a Markdown file with YAML front matter. Knowing the structure lets you author agents by hand, version them in git, and review pull requests that change agent behaviour.

---
name: code-improvement-advisor
description: Use this agent when the user asks for code improvement
  suggestions, readability fixes, performance tuning, or best-practice
  feedback across the project.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: sonnet
---

You are a senior code improvement advisor. Your job is to scan the
project, identify issues across readability, performance, and best
practices, and produce a prioritised list of suggestions.

Methodology:
1. Read the entire file before suggesting changes.
2. Group findings by severity (high / medium / low).
3. For each finding, show the current code and an improved version.
4. Do NOT modify files; you are an advisor only.

Project-aware behaviour:
- Respect existing patterns even if they aren't your favourite.
- Prefer minimal diffs over rewrites.
- Cite line numbers using file_path:line.

🏃 Running and observing your agent

With the agent saved, run it from Claude Code by mentioning it explicitly:

Use the code-improvement-advisor to review the entire project and
provide prioritised suggestions.

The main session will spawn the sub-agent, which runs in its own context. You’ll see live progress in the UI: tools called, files read, token usage. When the agent finishes, it hands back a single summary organised by severity:

Critically, if you stay in plan mode, the advisor won’t touch anything—it will only output the plan. From there you can either pick a subset and ask the main session to act on them, or write them into a plan.md for later.

👉 Run /context after the agent finishes to see how much of your main context budget you spent. Spoiler: if you delegated correctly, almost none.

✅ Best practices for designing sub-agents

Common mistakes & pro tips

Conclusion

Sub-agents are how Claude Code scales beyond “one big context window”. They let you delegate noisy, exploratory, or specialised work to a focused worker, keep your main session clean, and run multiple lines of reasoning in parallel. The built-in agents (Explore, Plan, General Purpose, Claude Code Guide) cover the common cases, and custom agents let you encode your team’s conventions, reviewer style, and project quirks into reusable Markdown files.

Start small. Build one advisor agent for your current project, commit it to .claude/agents/, and use it for a week. You will very quickly stop wondering why anyone codes without sub-agents.

Related reading: Claude Code vs Cursor AI comparison — when an AI agent deleted the production database