How to Build Claude Code Subagents: YAML Front Matter, Custom Agents, Misfire Fixes

Step-by-Step Breakdown

1. Understand the orchestrator–worker model

   Your main Claude Code session is the orchestrator. It delegates tasks to subagents that each start with a fresh, isolated context. This keeps your main context window clean and allows parallel execution. The main session sends a task to a subagent (e.g., "research Fireflies.ai") and the subagent reports back with results.

2. Understand the two subagent types

   Built-in subagents are Claude Code's native general-purpose agents — they're invoked automatically for things like web research without you building anything. Custom subagents are markdown files you create in .claude/agents/. Both types use the same YAML front-matter format and respond to progressive disclosure.

3. Create your agent file in .claude/agents/

   Each custom agent is a single .md file. Technically it is the same format as a skill in .claude/skills/ — the difference is location and intent. Name the file descriptively (e.g., clickup-searcher.md). The YAML front matter goes at the top; the agent instructions go below it.

4. Write the YAML front matter

   The four most important fields are name, description, model, and color. The description is the trigger — Claude Code reads only the front matter when deciding whether to invoke the agent, so a precise description prevents misfires. Optional fields include tools (allowed tools list), disallowed_tools, and mcp_servers.

5. Write the agent instructions

   Below the front matter, write step-by-step instructions for what the agent should do when invoked. These are only loaded after the description triggers a match, so they can be verbose without wasting tokens on every request.

6. Test and tune the description for misfires

   Invoke the agent naturally (e.g., "show me what the team committed this week"). If it doesn't fire, broaden the description to include more natural-language phrasings. If it fires when it shouldn't, narrow the description with more specific trigger conditions. Test iteratively — there's no shortcut.

7. Assign the right model per agent

   You can set model: claude-haiku-4-5-20251001 for research or read-only subagents while running Opus in your main session. This cuts cost significantly on high-volume delegated tasks. Set disallowed_tools: [Write, Edit] to enforce read-only behavior on agents that should never modify files.

Agent File Structure

YAML front matter keys

---
name: clickup-searcher
description: Search ClickUp for tasks, messages, and project status when asked
  about team work, commitments, weekly progress, or project updates
model: claude-haiku-4-5-20251001
color: green
tools: []
disallowed_tools: [Write, Edit, Bash]
---

Use the ClickUp MCP tools to search for the requested information.
Return a clear, structured summary of findings.
Do not modify any data — this agent is read-only.

Template adapted from the video. Adjust name, description, model, and instruction body for your use case. See the OpenClaw skills guide for the full front-matter reference.

Key YAML fields

• name — how you reference the agent in conversation ("use the clickup-searcher agent…")
• description — the trigger; Claude reads this to decide whether to invoke. Be precise.
• model — model ID for this agent (can differ from your main session model)
• color — UI indicator color in the Claude Code session panel
• tools — explicit allowlist; empty list means all tools permitted
• disallowed_tools — explicit denylist; useful for read-only agents
• mcp_servers — limit which MCP servers this agent can use

Common Errors & Fixes Covered

Gotchas & Caveats

• Progressive disclosure only reads YAML first — Claude loads just the front matter to decide whether to invoke. Critical context the agent needs must be either in the description or derivable once the full instructions are loaded. Don't assume the agent body is pre-loaded.
• Bigger model ≠ better results for every task — Haiku is often enough for research, lookups, and data retrieval. Reserve Opus for tasks that genuinely need deep reasoning.
• Subagents and skills are the same format — the only difference is the folder (.claude/agents/ vs .claude/skills/). Either location works with progressive disclosure.
• The general-purpose built-in agent also responds to progressive disclosure — if you haven't named your custom agent precisely, the built-in agent may match first.

Key Takeaways

• Subagents are just markdown files with YAML front matter — same format as skills, stored in .claude/agents/.
• The description field is the trigger; precision here directly determines whether the agent fires correctly.
• You can assign a cheaper model (Haiku, Sonnet) to a subagent while running Opus in the main session — significant cost savings on delegated work.
• Parallel subagents run in fresh contexts, keeping your main context window clean and cheaper over long sessions.
• Use disallowed_tools to enforce read-only agents that cannot accidentally edit files.