← 21.221.4 →
2019 words No Slides

Video 21.3: Creating Custom Subagents

Course: Claude Code - Parallel Agent Development | Section: 21. Subagents for Parallel Work | Length: 5 minutes | Presenter: Daniel Treasure

Opening Hook

The four built-in subagents cover most use cases, but sometimes you need something more specialized. Maybe you want an agent that only uses specific tools, or one with a custom system prompt optimized for code review. Creating custom subagents is easier than you think—Claude Code gives you two ways: the /agents command for guided creation, or manual AGENT.md files for full control. This video walks you through both.

Key Talking Points

What to say:

Two Ways to Create Custom Subagents

  1. The /agents Command (Easiest)
  2. Type /agents in Claude Code and follow the prompt
  3. Choose agent name, description, and capabilities
  4. Claude generates the AGENT.md file for you
  5. Great for: Quick creation, guided experience, less YAML knowledge needed

  6. Scope options: User-level (~/.claude/agents/) or Project-level (.claude/agents/)

  7. Manual AGENT.md Files (Full Control)

  8. Create a file in .claude/agents/ or ~/.claude/agents/
  9. YAML frontmatter + system prompt
  10. You write the exact YAML config and system prompt
  11. Great for: Complex requirements, reuse across projects, version control in git
  12. Scope options: Same as above

AGENT.md Structure (The Format You Need to Know)

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: claude-opus-4-6
---

Your system prompt goes here.
Be specific about what this agent should do.
  • name: Machine name (no spaces, lowercase, hyphens ok)
  • description: Human-readable description (shown when selecting agents)
  • tools: Allowlist of tools (only these are available)
  • model: Which Claude model (opus, sonnet, haiku)
  • System prompt: Everything after the --- separator

Tool Restrictions: Two Approaches - Allowlist (recommended): tools: [Read, Glob, Grep, Bash] — only these work - Denylist (less common): disallowedTools: [Write, Edit, Delete] — everything except these - Use allowlist for security and clarity - Use denylist only if you want "most tools except these specific ones"

Model Selection - opus: Full power, slowest, most expensive. For complex reasoning. - sonnet: Balanced. Good default for custom agents. - haiku: Fast, cheap. For focused, simple tasks. - Leave unspecified → inherits main agent's model

Scope: Where Your Agent Lives - Project scope (.claude/agents/): - Lives in your project repository - Team members on the project have access - Great for team conventions (e.g., "our project's code reviewer") - Checked into git, versioned - User scope (~/.claude/agents/): - Lives on your machine only - Accessible across all your projects - Great for personal workflows - Not shared with team

Skills Preloading (Optional) - You can preload skills when creating agents - Example: skills: [api-conventions, error-handling-patterns] - Helps agent understand your project's standards upfront - Good for reducing prompt overhead in custom system prompts

Permission Modes (Optional) - permissionMode: plan: Agent is read-only (like Plan agent) - Default (no mode): Full tool access within the allowlist - Useful for safety: "This agent can use Read/Glob but can't execute anything"

Persistent Memory (Optional) - memory: user — remembers context across your sessions - memory: project — remembers context for the project - memory: local — session-only (default, no persistence) - Useful for long-running agents that learn your patterns

What to show on screen:

  1. The /agents command flow
  2. Type /agents
  3. Show the prompt asking for agent name, description, capabilities
  4. Show Claude generating the AGENT.md file

  5. Show the created file in the editor

  6. Manual AGENT.md creation

  7. Create a new file in .claude/agents/code-reviewer.md
  8. Show the YAML frontmatter structure
  9. Show system prompt being written

  10. Save and reload

  11. Using the custom agent

  12. Invoke it in conversation or with explicit request
  13. Show it appearing in agent selection dropdown

  14. Show results coming back with the agent's specialized behavior

  15. Scope demonstration

  16. Show .claude/agents/ (project-level) directory structure
  17. Show ~/.claude/agents/ (user-level) structure
  18. Mention how scope hierarchy works (project → user → built-in)

Demo Plan

Setup (30 seconds): - Open Claude Code with a real project - Open the file explorer and navigate to .claude/agents/ directory - Have the AGENT.md template ready (or show it being created)

Method 1: Using /agents Command (1.5 minutes) 1. Say: "I want to create a specialized code reviewer that focuses on performance." 2. Type /agents and show the prompted flow 3. Walk through: - Agent name: "performance-reviewer" - Description: "Analyzes code for performance bottlenecks and optimization opportunities" - Capabilities: Choose "Read, Glob, Grep" (read-only, focused) - Model: Select "sonnet" (balanced) 4. Show Claude generating the AGENT.md file 5. Highlight the generated system prompt 6. Save it to project scope (.claude/agents/)

Method 2: Manual AGENT.md Creation (1.5 minutes) 1. Say: "For more control, you can write AGENT.md directly." 2. Create a new file: .claude/agents/api-designer.md 3. Type the YAML frontmatter: ```yaml

name: api-designer description: Designs REST APIs following OpenAPI 3.0 spec tools: [Write, Edit, Read, Glob] model: claude-sonnet

4. Write a focused system prompt: You are an API design specialist. When reviewing or designing APIs: - Always follow OpenAPI 3.0 specification - Prioritize clear, RESTful design patterns - Explain trade-offs between consistency and flexibility - Generate example requests and responses ``` 5. Save and show it appearing in agent selection

Using Your Custom Agent (1 minute) 1. Ask: "Performance-reviewer, analyze this function for bottlenecks" 2. Show the custom agent responding with focused analysis 3. Mention: "This agent only has read-only tools—it can't accidentally modify files" 4. Show how the custom system prompt shapes the behavior (vs. a general-purpose agent on the same code)

Optional: Tool Restriction Demo (30 seconds) 1. Say: "Notice the tools list. Let me show why that matters." 2. Try to do something the agent isn't allowed to do (e.g., call a tool not in its allowlist) 3. Show the agent declining and explaining why 4. Conclusion: "Tool restrictions keep your agents focused and safe"

Hierarchy and Scope (30 seconds) 1. Show the .claude/agents/ project directory 2. Mention: "If I also had ~/.claude/agents/, the project agents would take priority" 3. Show how to check which agents are available with agent listing

Code Examples & Commands

Creating via /agents Command

# In Claude Code prompt:
/agents

# Then follow the guided prompts:
# Agent name? performance-reviewer
# Description? Analyzes code for performance bottlenecks
# Capabilities? Read, Glob, Grep
# Model? sonnet
# Project or user scope? project

Manual AGENT.md: Code Reviewer

---
name: code-reviewer
description: Specialized code review focused on best practices and quality
tools: [Read, Glob, Grep]
model: claude-sonnet
permissionMode: plan
---

You are an expert code reviewer with deep knowledge of software engineering best practices.

When reviewing code:
1. Look for correctness, clarity, and maintainability
2. Identify potential bugs and edge cases
3. Suggest refactorings that improve readability
4. Ask clarifying questions about intent when unclear
5. Praise good patterns you see

Focus on constructive feedback. Explain why changes matter.
Keep a running list of issues by severity: Critical, Important, Nice-to-have.

Manual AGENT.md: Documentation Generator

---
name: docs-generator
description: Generates clear API documentation and usage examples
tools: [Read, Write, Edit, Glob]
model: claude-haiku
---

You are a technical documentation specialist. Your job is to generate clear, example-rich documentation.

When generating docs:
1. Always include working code examples
2. Document edge cases explicitly
3. Use a conversational but precise tone
4. Structure with headers, lists, and code blocks
5. Include "Before/After" examples when relevant

Output Markdown-formatted documentation ready for publishing.

Manual AGENT.md: Security Auditor

---
name: security-auditor
description: Audits code for security vulnerabilities and best practices
tools: [Read, Glob, Grep]
model: claude-sonnet
permissionMode: plan
---

You are a security-focused code auditor. Your role is to identify potential security risks.

When auditing:
1. Look for injection vulnerabilities (SQL, command, XSS)
2. Check authentication and authorization logic
3. Identify hardcoded secrets or credentials
4. Review cryptography and hashing implementations
5. Check for proper input validation
6. Flag insecure randomness or PRNG usage

Report findings with severity (Critical/High/Medium/Low) and remediation advice.

Invoking Custom Agents

# Explicit invocation
"Use the performance-reviewer agent to analyze this function"

# Implicit (Claude picks if the task matches agent description)
"Review this API endpoint for performance—focus on DB queries"
# → Claude may auto-select performance-reviewer if context matches

Agent Scope Resolution (For Reference)

Priority order when multiple agents have same name:
1. Project-level agents (.claude/agents/)
2. User-level agents (~/.claude/agents/)
3. Built-in agents (Explore, Plan, General-Purpose, Bash)

Gotchas & Tips

Gotcha: "I created an AGENT.md but it's not appearing" - Check the scope. If you created it in .claude/agents/, is your CLI looking in the right directory? - Check the YAML syntax. Invalid YAML will silently fail. - Restart Claude Code to reload agent definitions.

Gotcha: "My agent is too slow" - Check the model. If you specified model: opus, switch to sonnet or haiku. - Check tools. Fewer tools = faster execution. Remove unnecessary ones from the allowlist.

Gotcha: "The agent ignores my tools list" - Make sure tool names are capitalized correctly: Read, not read. Bash, not bash. - Check for typos. If you misspell a tool name, it's silently ignored.

Tip: Start with read-only tools - When creating a new agent, default to tools: [Read, Glob, Grep] - Add write/edit tools only if the agent truly needs them - Safer, cheaper, less error-prone

Tip: Write a focused system prompt - Generic prompts lead to generic behavior - Specific instructions lead to specialized behavior - Example: "Focus on database query efficiency" → better performance analysis than "review code"

Tip: Use permissionMode: plan for safety - If your agent shouldn't modify files, add this - Prevents accidents, doesn't cost extra - Good for analysis, review, and audit agents

Tip: Test your custom agent immediately - Create the agent, then invoke it on a small sample - See if it behaves as expected - Adjust the system prompt if needed—don't let a mediocre agent sit unused

Tip: Version control your project agents - Keep .claude/agents/ in git - Your team will inherit your custom agents - Great for enforcing team standards

Lead-out

Now you know how to create custom subagents tailored to your workflow. But creating an agent is only half the story—you also need to know when to run them in the foreground (blocking, interactive) versus the background (concurrent, pre-approved). In the next video, we'll explore foreground vs. background execution and when each one makes sense.

Reference URLs

Prep Reading

  • Docs: "AGENT.md Format Reference" — understand all optional fields
  • Examples: Look at how built-in agents are configured (if available)
  • Think: What specialized agents would improve your workflow?
  • Practice: Write 2-3 custom AGENT.md files before recording to be comfortable with the syntax

Notes for Daniel

This video has two distinct flows: the guided /agents command and the manual AGENT.md approach. Both should feel equally viable. Don't make one seem obviously better.

The /agents command is great for beginners. Manual AGENT.md is great for control and version control. Show both so viewers can choose.

The YAML syntax is important but not complicated. Take time to explain field by field, or viewers will get lost. Consider a visual highlighting each field.

The system prompt part is where customization happens. Spend time showing how different prompts lead to different agent behaviors. This is the "magic" that makes custom agents worth creating.

Demo choosing between tools. Show why a security auditor doesn't need Write/Edit (it's read-only work). This builds intuition about tool design.

Mention upfront: "You don't need to create custom agents for everything. But when you find yourself asking the same thing over and over, that's when a custom agent pays off."

Tone: You're teaching craftsmanship. "Here's how to build a tool tailored to your workflow, not someone else's generic solution."