13.1 Subagents: Specialized AI Roles

Course: Claude Code - Enterprise Development Section: Extending Claude Code Video Length: 3-4 minutes Presenter: Daniel Treasure

Opening Hook

"Right now, you're delegating work through prompts. What if you could delegate to specialized AI roles with their own models, tools, and permissions? That's what subagents do. Let me show you how to set one up and why it matters for enterprise workflows."

Key Talking Points

1. What Are Subagents?

What to say: "Subagents are autonomous AI assistants that Claude Code can delegate tasks to. Each one has its own personality defined by a prompt, its own set of tools it can use, a specific model it runs on, and explicit permissions. You ask Claude to delegate a task by description—the system matches that description to the best-fit subagent."

What to show on screen: - Terminal: list agents with /agents command - Show the built-in agents: Explore (read-only, haiku), Plan (outline generator, inherit model), general-purpose (full tools, inherit), Bash (shell-only) - Visual: highlight that each has its own AGENT.md file with different configurations

2. One Responsibility, Clear Trigger

What to say: "The design principle is simple: one subagent, one clear job. A code reviewer agent doesn't also do DevOps work. A security auditor doesn't write features. Clear descriptions help Claude automatically pick the right agent for the task. If the description is vague, it picks wrong."

What to show on screen: - Open .claude/agents directory structure - Show example AGENT.md frontmatter with clear description field - Highlight: vague description vs. specific description (side-by-side comparison)

3. The AGENT.md Config File

What to say: "Every subagent lives in a Markdown file with YAML frontmatter. Name, description, allowed tools, the model it runs on, permission mode—all defined right there. You can scope memory to that agent alone. You can set maximum turns so it doesn't loop. You can even attach hooks to run checks when it uses a tool."

What to show on screen: - Open a sample AGENT.md file - Walk through frontmatter fields: name, description, tools (list), disallowedTools, model (sonnet/opus/haiku/inherit), permissionMode (read-only, workspace, system), maxTurns, memory (user/project/local), hooks - Expand frontmatter section; show it's YAML above the --- divider

4. Where Agents Live and Scope

What to say: "Put a subagent in your project at .claude/agents// and it's only available in that project. Put it in ~/.claude/agents// and every project sees it. Choose based on whether this is specialized work for one codebase or a tool you use everywhere."

What to show on screen: - File browser: show project-scoped .claude/agents folder - File browser: show home-scoped ~/.claude/agents folder - Highlight: scope dropdown in Create Agent dialog

5. You Can't Create Subagents (Yet)

What to say: "This matters because subagents are managed through Claude Code's UI or by hand-editing the AGENT.md file. You can't ask Claude to create a new subagent for you—subagent design is your call. The built-in agents are there; you customize them or build your own."

What to show on screen: - Interactive creation flow: /agents → Create new agent dialog - Walk through: scope selection, generate vs. manual template, tool selection, model choice, save location - Show the resulting AGENT.md file in the editor

Demo Plan

(0:30) Open /agents command, show built-in agents list (Explore, Plan, general-purpose, Bash)
(1:00) Open Explore agent's AGENT.md—walk frontmatter: haiku model, read-only, clear description
(1:45) Open general-purpose agent—show all tools, inherit model, delegation matcher
(2:15) Create a new subagent interactively: /agents → Create → Project scope → Security auditor role → select Bash, Read, Grep tools → choose Haiku model → save
(3:00) Show saved AGENT.md with new config; discuss one-tool design and trigger-friendly description
(3:30) Discuss when to use subagents: parallelization, permission boundaries, role separation

Code Examples & Commands

List and create agents

/agents

Creates or lists agents. Opens interactive dialog for new agent creation.

AGENT.md minimal example

---
name: SecurityAuditor
description: "Reviews code for security vulnerabilities, hardcoded credentials, and unsafe patterns. Runs static analysis."
tools: [Bash, Read, Grep]
disallowedTools: [Write, Edit]
model: haiku
permissionMode: read-only
maxTurns: 5
memory: project
---

You are a security-focused code auditor. When asked to review code, focus on:
- Hardcoded secrets or credentials
- SQL injection risks
- Path traversal vulnerabilities
- Unsafe deserialization
- Missing input validation

Be concise. Report findings as a prioritized list.

AGENT.md with hooks

---
name: CodeFormatter
description: "Formats and lints Python and JavaScript code to project standards."
tools: [Write, Bash]
model: haiku
hooks:
  - event: PostToolUse
    matcher: Write
    hooks:
      - type: command
        command: "python -m black --check {filepath}"
---

You are a code formatter. After making edits, validate they pass linting.

Resume a subagent session

When a subagent returns its agentId, pass it back to continue:

/agents <agentId>

Gotchas & Tips

The description matters more than you think. Vague descriptions like "general helper" cause Claude to pick the wrong agent. Write descriptions that describe the job, not the tool. Bad: "Uses Bash." Good: "Optimizes database queries by analyzing logs and suggesting indexes."

Tools define responsibility. If an agent has Write and Edit, it can modify your code. If it has Bash and no file writing, it can run commands safely but not change files. Align tool grants with the job.

Memory is scoped per agent. If you set memory: project, that agent's conversation history is saved only for that agent in that project. Perfect for continuity within a specialized role. Use memory: local for one-off work that shouldn't persist.

maxTurns prevents loops. A security auditor that can't finish work in 5 turns is probably stuck. Set a reasonable ceiling.

Subagents can't create other subagents. Agents don't design agents. You do. They're tools for delegation, not auto-scaling.

Lead-out

"Subagents are your specialized workforce. Each one does one job well, with the right tools, the right model, and the right permissions. In the next video, we'll show you hooks—the automation layer that runs checks automatically when agents (or you) use tools. That's where you enforce standards at scale."

Reference URLs

Claude Code Subagents documentation
AGENT.md schema reference
Permission modes explained (read-only vs. workspace vs. system)

Prep Reading

Agent design best practices
Tool security boundaries
Memory scoping for agents

Notes for Daniel: Prepare 2-3 sample AGENT.md files beforehand so you don't spend time typing during the demo. The SecurityAuditor example works well because it's obviously constrained (read-only, Bash + analysis tools). If time is tight, skip the "Resume a subagent session" part of Code Examples—it's nice-to-have context. Emphasize that "you can't ask Claude to create agents" because viewers often assume agents auto-spawn like in other AI systems. They don't.

Quick Reference