When you install Claude Code, a set of agents is already there — invisible, ready, and requiring no setup.
They’re the built-ins. But the system also allows any file to
.md with the right frontmatter
become a new agent—a custom. The diagram below shows the fork: the maestro
reads name e description, decides which of the two branches to follow, and dispatches the work.
↑ The orchestrator doesn't need to know whether the agent is built-in or custom — it reads name e description and decides. The branching is internal to the system.
💡 Core concept
For the conductor, built-in and custom are identical: both have a name, description, and tools.
The difference is origin — the built-ins come with Claude Code; you create the custom ones with a file
.md within
.claude/agents/.
Detailed content
What built-ins are
Claude Code registers four agents during installation. They don’t appear as files in your project — they’re embedded in the binary. You invoke them by their exact name or let Claude choose automatically.
Why know each built-in
When you let Claude choose, it uses the description to decide. Without knowing the built-ins, you won't notice when the selected one is unsuitable — and you'll create an unnecessary redundant custom one.
Tip: check /agents before creating any custom item.
Key concepts
- →Embedded in the binary — they aren't files, don't appear in the project, and don't need your maintenance.
- →Explore is read-only — by design, it has no write tools; ideal for safe research.
- →general-purpose ≠ custom — even if you pass a "system prompt" when invoking general-purpose, it doesn't become a custom agent; it's a temporary persona.
What the confusion is
Many people discover they can invoke the general-purpose with an additional instruction
— “act as a critical code reviewer” — and think you’ve created a new agent. You haven’t. You’ve created a ephemeral persona:
it exists only in that conversation, has no name of its own in the system, cannot be invoked later, and does not appear in the /agents.
Why the distinction matters
✅ Use an ephemeral persona when
- ✓It’s a one-off task, not a repetitive one
- ✓You don’t need the agent tomorrow
- ✓Behavior varies with each invocation
❌ Doesn't replace custom when
- ✗You use the same pattern every week
- ✗Others on the team need to invoke the same agent
- ✗Needs restricted or specialized tools
Key concepts
- →Ephemeral persona — exists only in the current conversation; it dies when you close the session.
- →Custom is persistent — lives in the file
.md, can be versioned in Git, and any team member can use it. - →Practical rule — if you'll repeat it more than 3 times, create a custom.
What a custom agent is
A custom agent is a Markdown file with YAML frontmatter at the top. Saved in
.claude/agents/
(project) or ~/.claude/agents/ (global),
it is registered automatically — no installation or restart needed.
Why this format works
Claude registers the agent by reading only the frontmatter. The body of the .md é o
system prompt from the agent — it's only read when the agent is invoked. This allows for a huge agent catalog
with no token cost to the conductor: progressive disclosure into action.
Key concepts
- →Required frontmatter:
nameedescription. The rest is optional. - →Scope: agents in
.claude/agents/from the project are available only within it; global ones are in~/.claude/agents/. - →Versionable: the file
.mdgoes into Git with the project—the whole team uses the same definition.
What progressive disclosure means here
The orchestrator doesn’t load each agent’s entire body into context to decide which one to use.
It reads only name e
description of all available agents —
a concise catalog. The complete system prompt (the body of the .md) is only
loaded when the agent is actually invoked.
Why this matters
name + description of all agents. Cost: minimal..md is loaded—in the agent’s window, not the conductor’s.Key concepts
- →Description as a contract: is the only thing that determines when the agent is selected. A vague description = the wrong invocation.
- →You can have 50 agents without paying selection tokens: the catalog of names+descriptions is concise.
- →Be careful with long descriptions: Track 2 will teach you how to "trim" it down to just the essential trigger.
The cost model
Each token in the conductor’s context costs money and attention. The built-in/custom model avoids unnecessary costs: the conductor loads metadata (name + description), not the full system prompt.
✅ With progressive disclosure
- ✓Maestro loads ~5 tokens per agent (name)
- ✓The system prompt only enters the agent’s window
- ✓Orchestrator context stays clean
- ✓Scale to dozens of agents at no extra cost
❌ No separation (inline)
- ✗Each agent’s system prompt in context
- ✗Orchestrator context grows with every turn
- ✗Cost multiplies with the number of agents
- ✗Less room for the actual work
Why this scales
20 agents × 300 words each = 6,000 words of "configuration" alone without progressive disclosure. With the separation: ~100 words of metadata; each agent's 300 words stays tucked away until called.
Golden rule: a description is less than 2 lines. The details go in the body of the .md.
Key concepts
- →Metadata ≠ behavior — the description determines selection; the .md body determines execution.
- →Separate responsibilities — orchestrator decides, agent executes, each with its own context.
- →The real cost is from attention, not just money — a crowded context produces worse answers.
What /agents is
Type /agents in Claude Code to open the agents panel. It lists everything: system-registered built-ins and custom agents found in the folders
.claude/agents/ from the project and
~/.claude/agents/ global.
This is also where you create new agents with the interactive assistant.
↑ Illustrative output from the /agents. Built-ins appear first; custom agents show which folder they came from.
Why verify before creating
Before writing a custom one, open the /agents
and read the built-in descriptions. In many cases — especially code search, planning, and general tasks —
a built-in already does what you need, with zero configuration.
Recommended flow: /agents
→ read the descriptions → if none fit, create a custom one. Never the other way around.
Key concepts
- →/agents is the inventory: always the source of truth about what’s available in the current context.
- →Visible scope: /agents shows agents for the current project + global agents. In another project, the list changes.
- →Create with the wizard: when pressing n in /agents, Claude guides you through filling out the frontmatter — a good entry point for your first custom agent.
Prompts ready to use now
Copy any of these prompts and paste them into Claude Code to explore this module’s concepts in practice.
Expected result: Claude uses the /agents internally and returns the list with summarized descriptions.
Claude will compare the available built-ins with the task and recommend the right approach.
Good for experimenting with progressive disclosure: see how the frontmatter alone already defines the contract.
Exercise
Access the /agents on your machine and
catalog the available built-ins.
For each one, write: a name, a one-line description, and an example task where it would be the right choice.
How to do it
- Open Claude Code and type
/agents. - Read the descriptions of each built-in (not the custom ones yet).
- For each built-in, write: name | brief description | example of a concrete task.
- Identify which built-in you’d use most often in your work context.
✅ Verification criteria
You've completed the exercise if you can answer:
- →Which built-in is read-only? (answer: Explore)
- →Which one should you use to create a refactoring plan? (answer: Plan)
- →Which one should you use when none of the others fit? (answer: general-purpose or claude)
Bonus
After cataloging the built-ins, identify a task from your day that no built-in covers well. Write down the name you'd give the custom agent and a two-line description. You'll create this agent in Track 2.
✅ Module summary
Next module:
1.5 — The deciding question. How to tell when a subagent helps — and when it complicates things.