You already understand what a subagent is and know how to write your .md and knows the difference between project and global. Now comes the practical question: how do I create a real agent from scratch? The command /agents is Claude Code's native wizard—it lists what's available, opens the guided creator, and lets you trim the result. In this module, you'll create a complete agent (plan-roaster) and learn exactly how Claude decides which agent to call.
Wizard flow /agents: from command to active agent in 3 steps
Detailed content
🔍 The /agents command — view and create
Your subagent control panel
O /agents is the entry point for everything related to custom agents in Claude Code. It displays the complete list of agents available in the project and globally, and opens the guided creation wizard.
- • Lists all available agents (project + global)
- • Shows where each .md file is saved
- • Opens the interactive creation wizard
- • Lets you edit existing agents
- • Displays the configured description, tools, and model
- • Doesn't create the file manually (the wizard creates it)
- • Doesn't run the agent directly
- • Doesn't show Claude Code built-ins
- • Doesn't sync with other projects
- • Doesn't define when Claude activates (that's the description)
When running /agents without parameters, Claude Code scans the directories .claude/agents/ from the project and the global directory, reads the frontmatter of each .md and make a list with the name, truncated description, and location.
Before creating a new agent, always list the existing ones — you may already have one that covers the use case, or discover names that conflict with what you planned to create.
Project takes precedence over global when names conflict. The creation wizard warns you if the name already exists. The list includes Claude Code built-ins, separated from your custom agents.
⚡ Generate-with-Claude × manual
Two ways to fill out the .md — when to use each one
Inside the wizard, the option Generate with Claude uses the current model to draft the file .md from a high-level description you type. It’s the fastest starting point — but the generated output almost always needs trimming in the description.
Claude writes the body, chooses tools, and suggests a model. You describe the goal in natural language. Output in seconds. Requires trimming the description to avoid overly long text.
You write the .md from scratch in an editor. Full control, no surprises. Ideal when you already have a template ready or are iterating on an existing agent.
Choosing between the two modes determines creation speed vs. control over the result. Generation is great for the first draft; manual work is better for fine-tuning.
Automatically generated agents tend to have verbose descriptions that trigger at the wrong time. Knowing when to trim them prevents costly misfires.
Practical rule — generate the draft, open the .md and cut the description down to no more than 2-3 sentences with an explicit trigger. The body can be detailed; the description should be surgical.
🧩 Wizard choices: tools, model, color, memory
The four decisions that define the agent's behavior
The wizard guides you through each field, but you can leave it blank and edit it later directly in the .md. The field tools is the most critical—agents with unrestricted access can take unexpected actions.
List of allowed tools. Prefer explicit lists (e.g., ["Read","Bash","WebSearch"]). Omit it = inherit all tools from the parent context.
Model to use: haiku for quick/low-cost tasks, sonnet for balance, opus for heavy reasoning.
Agent badge color in the Claude Code UI. Purely aesthetic — useful for quickly distinguishing agents in the list of /agents.
Controls whether the agent can read from/write to persistent memory (allow / deny). In most cases, deny is safer—specialist agents don’t need memory.
The wizard uses conservative defaults: no explicit tools, no model set. In production, you’ll almost always want to declare tools e model for predictable behavior.
Agent without model by default inherits the parent Claude's model—it can change from session to session depending on your plan. Pinning the model ensures predictable costs and latency.
Recommended production minimum: name, description (surgical), tools (explicit list), model. Color and memory are optional.
🔥 plan-roaster case: create and trim
From idea to working agent — complete walkthrough
When you use "Generate with Claude," the model generates a long, detailed description. It seems good — but a description like that triggers the agent in contexts that are too generic. Trimming is mandatory.
/agents → Create → name: plan-roasterThe wizard asks for a name. Use kebab-case. This agent will critically review plans.
E.g.: "agent that reviews implementation plans, points out blind spots, risks, and better alternatives — like a skeptical senior engineer"
.claude/agents/plan-roaster.md and trim the descriptionCut it down to 2–3 sentences: the when triggers + the that do. Remove any context paragraph — that belongs in the body.
@plan-roaster revise este planoIf it launches correctly, check whether the output is detailed. If it’s generic, enrich the body of the .md.
Progressive disclosure applied to the description: Claude reads only the first tokens of the description to decide whether to activate the agent. Everything after the main trigger rarely matters for activation.
A 5-line description with many unrelated contexts creates ambiguity — Claude may activate the agent even when it isn’t ideal. 2-3 sentences with a clear trigger are more precise.
Concise description formula: "Use [exactly when]. [What it does in 1 sentence]. [Optional: trigger examples]." The rest goes in the body of the .md, which the agent reads after it’s activated.
🎯 Four ways to invoke an agent
Automatic, proactive, @name, and --agent
Claude reads the description of every available agent on each turn. If your prompt matches an agent’s description, it’s activated automatically — without you having to ask. This is automatic mode. But you can force other modes.
Claude reads the description and activates the agent if the context matches. You do nothing — it decides. It depends on a precise description.
The description includes "Use proativamente quando..." — Claude checks whether it should trigger even if you don't explicitly ask, such as after commits or when opening a PR.
You type @plan-roaster revise isto. Guaranteed activation regardless of the description. More explicit — fewer surprises. Ideal when testing a new agent.
On the command line: claude --agent plan-roaster "revise o plano". Useful in scripts and automations where you're not in interactive mode.
When two agents have descriptions that match the same prompt, Claude uses the full conversation context to decide which one is more specific. Project agents take precedence over global agents with the same name.
If you have a code-reviewer global and one for the project; the project one always takes precedence. This allows project-specific customizations without removing the global one.
Priority order: 1) invocation @nome (forced), 2) project agent (auto), 3) global agent (auto), 4) built-in. Unique names eliminate the conflict.
🔧 Misfire and fix
When the agent fires incorrectly — and how to fix it
- • Agent activates on prompts that have nothing to do with it
- • Two agents activate at the same time
- • Agent never activates — even when asked
- • The wrong agent activates (description collision)
- • Generic output: the .md body wasn't read
- • Trim the description — remove unnecessary context
- • Rename or separate descriptions with distinct triggers
- • Add "Use proactively when [exact phrase]"
- • Use a prefix in the name:
proj-code-reviewer - • Enrich the .md body with detailed instructions
Ask Claude: "Why was the agent plan-roaster didn't trigger on my last prompt?" — it will explain which description it read and why it didn't match. Use that information to adjust.
The description is rarely perfect the first time. The cycle is: write → test with 5+ varied prompts → observe when it triggers and when it doesn't → adjust the description → repeat.
Production agents that trigger incorrectly can waste tokens or disrupt your workflow. Iterating on the description is an agent’s main maintenance cost.
Test 5 prompts: 2 that should trigger, 2 that shouldn't, and 1 edge case. If the accuracy rate is 4/5 or better, the description is good. If it's lower, iterate.
✂️ Trimming the generated description
The art of precise trimming — progressive disclosure
Claude Code uses the descriptions of all available agents as part of its decision-making context on every turn. Long descriptions consume more tokens in this selection window — and semantic ambiguity in them leads to misfires. The optimized description is the one that passes the 5-prompt test with the fewest words.
"This agent specializes in critical reviews of implementation plans. It is designed to analyze technical and strategic planning documents, identifying gaps, blind spots, overlooked risks, hidden dependencies, and more efficient alternatives. It acts like a skeptical senior engineer..."
"Use proactively when the user presents a plan, spec, or implementation document for review. Critically review it like a skeptical senior engineer: point out blind spots, risks, and alternatives."
The 3-part formula: (1) an explicit trigger with "Use [when/proactively when]...", (2) what it does in 1 active-voice sentence, (3) optionally, trigger examples as a semantic hint.
Descriptions that follow this formula have a misfire rate close to zero in empirical tests. “Use when” anchors Claude to the right intent before any semantic ambiguity.
Template: "Use proativamente quando [trigger]. [O que faz]. [Hint adicional opcional]." — 2-3 sentences max. Put all operational context in the body of the .md.
📄
Real example: plan-roaster.md
Complete file — trimmed description, rich body, minimal tools
--- name: plan-roaster description: "Use proactively when the user presents a plan, spec, or implementation document. Critically review it: point out blind spots, risks, and better alternatives." tools: [Read] model: claude-sonnet-4-5 color: red --- # Plan Reviewer (plan-roaster) You are a skeptical senior engineer. Your job is to review implementation plans with constructive skepticism. Never approve without asking questions. ## Review Protocol 1. Read the full plan before commenting 2. Identify the 3 biggest gaps or risks 3. For each risk, suggest a concrete mitigation 4. Point out unstated implicit dependencies 5. Question the time/cost assumptions 6. Conclude with a verdict: Approve / Revise / Reject ## Tone Straight to the point. No unnecessary praise. Use numbered lists. Maximum 400 words in the output.
- • Description trimmed to 3 sentences with an explicit trigger
- •
tools: [Read]— minimum necessary (read-only, no writing) - • Detailed body with a 6-step protocol — this gets read after of enabled
- • Explicitly defined tone — avoids generic responses
💬 Ready-made prompts
Copy, paste, and use now
/agents → Create → nome: plan-roaster → Generate with Claude → "revisor crítico de planos como engenheiro sênior cético"
@plan-roaster revise o plano em docs/plan.md e me dê os 3 maiores riscos
Por que o agente plan-roaster não disparou quando eu disse "revise meu plano de migração"? O que estava na description que não combinou?
🖥️
Simulated screen: wizard /agents
Illustrative recreation — not a real screenshot
🏋️ Exercise: create and invoke an agent by name
- 1.Open Claude Code in your project and run
/agents— note how many agents already exist. - 2.Create an agent named
bug-hunterusing "Generate with Claude" with the goal: "agent that analyzes code and finds potential bugs before a PR". - 3.Open the
.mdgenerated and trim the description to a maximum of 3 sentences using the formula in topic 7. - 4.Invoke by name:
@bug-hunter analise o arquivo main.py e me dê os 3 maiores riscos. - 5.Test 3 prompts that should NOT activate the agent and confirm that it doesn't trigger.
.claude/agents/bug-hunter.md exists in the project
@bug-hunter returns a structured analysis with numbered bugs
.md filled in
📚 Module summary
/agents is the complete dashboard—lists, creates, and edits agents
You've completed Track 2 — now you know how to create agents in practice. Track 3 goes deeper into model, cost, and orchestration: which model to choose for each task, how to chain subagents, and how to measure the real cost of a multi-agent system.