← 10.510.7 →
1509 words Slides

10.6 Creating Team Subagents

Course: Claude Code - Power User Section: Customizing Claude Code Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

One Claude isn't always the right Claude. You might want a security-focused reviewer, a style enforcer that's obsessive about naming, or a domain expert who deeply understands your architecture. Subagents are specialized Claude instances—each with its own skills, permissions, and personality—that you can spawn for specific jobs.

Key Talking Points

1. What Are Subagents?

  • Specialized Claude instances for specific roles or domains
  • Defined in ~/.claude/agents/ (user) or .claude/agents/ (project)
  • Each has its own permissions, tools, model, memory, and skills
  • Invoked via custom commands or programmatically from main Claude
  • Communicate results back to the user or main agent What to say: "Subagents are like hiring specialists. Your main Claude is the generalist. Subagents are the code review expert, the security auditor, the architecture advisor." What to show on screen: Agent definitions showing AGENT.md with frontmatter. Show how to invoke: claude /code-review which spawns a review-specialized subagent.

2. Common Subagent Patterns

  • Code Reviewer: bugs, security, best practices, performance—read-only, detailed feedback
  • Style Enforcer: naming conventions, formatting, structure—strict rules, clear violations
  • Domain Expert: architecture, design patterns, system design—deep knowledge, high bar
  • Security Auditor: vulnerability scanning, auth flows, data protection—paranoid, thorough
  • Test Generator: unit tests, integration tests, edge cases—comprehensive, pragmatic
  • Documentation Writer: docstrings, READMEs, API docs—clear, complete, user-focused What to say: "Each specialist has a point of view. A style enforcer doesn't care about performance. A security auditor doesn't care about code style. Separation of concerns." What to show on screen: Show 3-4 agent definitions. Demonstrate invoking one and getting specialized output.

3. Building a Subagent: Frontmatter and Instructions

  • name: agent identifier (e.g., "code-reviewer", "security-auditor")
  • description: what this agent does
  • tools: which tools it has access to (read, bash, git, etc.)
  • disallowedTools: explicitly block tools (security)
  • model: override model (Opus for deep thinking, Haiku for speed)
  • permissionMode: override permissions (review-only for reviewer)
  • maxTurns: limit conversation length (e.g., 5 turns for quick reviews)
  • memory: where to store state (user, project, local, or none)
  • skills: which custom skills this agent has What to say: "An agent definition is like a job description. 'This agent is a code reviewer with read-only access, uses Opus for thinking, and has a 5-turn limit'." What to show on screen: AGENT.md file structure. Show frontmatter fields. Show instruction prompt below.

4. Memory and State in Subagents

  • User memory: ~/.claude/agent-memory/[agent-name]/ (persistent across projects)
  • Project memory: .claude/agent-memory/[agent-name]/ (shared team state, version-controlled)
  • Local memory: .claude/agent-memory-local/[agent-name]/ (personal, not shared, gitignored)
  • No memory: stateless, no recall between invocations What to say: "Memory lets agents learn. A test generator can remember your testing patterns. A security auditor can track previously found vulnerabilities." What to show on screen: Memory directories showing what's stored. Show an agent using memory to improve over time.

5. Coordination Between Agents and Main Claude

  • Main Claude can invoke subagents via /agent command
  • Subagents return results to main Claude
  • Main Claude synthesizes results and acts on them
  • Useful for specialized tasks that need orchestration What to say: "You don't switch between agents manually. Main Claude calls the right specialist, gets the report, and decides what to do with it." What to show on screen: A workflow where main Claude invokes a code-reviewer subagent, gets feedback, then applies fixes.

Demo Plan

  1. Open .claude/agents/ directory structure
  2. Show an existing agent (AGENT.md) with frontmatter
  3. Create a new agent from scratch:
  4. Create directory .claude/agents/code-reviewer/
  5. Create AGENT.md with frontmatter
  6. Write the instruction prompt for code review
  7. Invoke the agent: claude /code-review <filepath>
  8. Show output demonstrating specialized analysis
  9. Create a second agent (security-auditor or style-enforcer)
  10. Demonstrate agent memory by invoking the same agent twice and showing learning

Code Examples & Commands

List available agents:

ls -la .claude/agents/
# or
claude agents list

Agent directory structure:

.claude/agents/code-reviewer/
├── AGENT.md           # The agent definition
├── context/           # Optional context files
│   ├── best-practices.md
│   └── common-patterns.md
└── memory/            # Agent's persistent state (auto-created)
    └── findings.md

AGENT.md (code-reviewer example):

---
name: code-reviewer
description: "Specialized code reviewer focusing on bugs, security, and best practices"
tools: ["read", "bash"]
disallowedTools: ["write", "git"]
model: "claude-opus-4-6"
permissionMode: "review-only"
maxTurns: 5
memory: "project"
skills: ["review"]
---

# Code Reviewer Subagent

You are a meticulous code reviewer. Your job: find bugs, security issues, and violations of best practices.

## Scope
Review the provided code for:
1. **Bugs:** logic errors, edge cases, null pointer risks
2. **Security:** injection vulnerabilities, auth bypass, data leaks
3. **Performance:** O(n²) loops, memory waste, unnecessary allocations
4. **Best practices:** code clarity, maintainability, testability
5. **Anti-patterns:** common mistakes in this language/framework

## Instructions
1. Read the code carefully
2. Identify 3-5 key issues (not nitpicks)
3. For each issue:
   - Explain what's wrong
   - Severity: critical, high, medium, low
   - Suggest a fix
4. If no issues, say so explicitly ("Code looks good. No issues found.")

## Output Format
- Each issue on separate line
- Format: [SEVERITY] Issue title - brief explanation - fix
- Don't comment on style; focus on correctness and safety

## Memory
Track issues you've found before to avoid redundant feedback.

AGENT.md (style-enforcer example):

---
name: style-enforcer
description: "Strictly enforces naming conventions, formatting, and structure rules"
tools: ["read"]
disallowedTools: ["write", "bash"]
model: "claude-haiku-4-5"
permissionMode: "review-only"
maxTurns: 3
memory: "none"
---

# Style Enforcer Subagent

You are extremely strict about code style and conventions.

## Rules (Project-Specific)
- Variable names: camelCase
- Functions: verb + noun (getUserById, not get_user_by_id)
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Private methods: _prefixed
- Max line length: 100 characters
- Import order: stdlib, third-party, local

## Instructions
1. Check every identifier for naming violations
2. Check line length and formatting
3. Check import order
4. Report violations only—don't suggest refactoring beyond style

## Output Format
- Line number: [violation] - explanation
- Example: "Line 42: [naming] use camelCase for variables, not snake_case"

AGENT.md (security-auditor example):

---
name: security-auditor
description: "Security-focused analyzer looking for vulnerabilities"
tools: ["read", "bash"]
disallowedTools: ["write", "git"]
model: "claude-opus-4-6"
permissionMode: "review-only"
maxTurns: 10
memory: "project"
context: ["owasp-top-10.md", "auth-vulnerabilities.md"]
---

# Security Auditor Subagent

You are paranoid about security. Your job: find vulnerabilities before they're exploited.

## Focus Areas
1. Authentication & authorization
2. Data validation & injection
3. Cryptography & secrets
4. API security
5. Error handling & information leakage

## Instructions
1. Analyze code for security flaws
2. Cross-check against OWASP Top 10
3. Consider threat models
4. Report findings with severity and remediation

## Output
- Issue: [vulnerability name]
- Severity: critical/high/medium/low
- Details: what's wrong
- Fix: how to fix it
- Example: [if applicable]

Invoke a subagent:

# From main Claude
claude /code-review src/api.ts

# Or programmatically
claude agent code-reviewer --input src/api.ts

Check agent memory:

cat .claude/agent-memory/code-reviewer/findings.md

Create agent with custom context:

---
name: architecture-advisor
description: "Architectural review and design guidance"
tools: ["read", "bash"]
model: "claude-opus-4-6"
memory: "project"
context: ["architecture.md", "design-patterns.md"]
---

# Architecture Advisor

You understand our system architecture deeply. See context for system diagrams and patterns.

Review proposed changes for architectural alignment and design quality.

Gotchas & Tips

Gotcha: Subagents are stateful. If you create an agent without memory, it won't learn. If you give it memory, it accumulates over time—clean it up occasionally.

Tip: Limit maxTurns for focused agents. A code reviewer should give feedback in 1-2 turns, not 10. Force conciseness.

Tip: Use disallowedTools to prevent accidents. A security auditor shouldn't have write access, period.

Gotcha: Agent memory is in .claude/agent-memory/ (project, version-controlled) or .claude/agent-memory-local/ (personal, gitignored). Don't accidentally commit local findings.

Tip: Agents with different models serve different purposes. Use Opus (slower, deeper) for architecture and security. Use Haiku (faster, lighter) for style enforcement.

Tip: Document agent context in files they can read. A security auditor should have access to OWASP guidelines and your threat model.

Lead-out

Subagents specialize Claude for different roles. When you're done building your team of specialists, the last step is sharing everything—your settings, agents, skills, and standards—across projects so your whole team benefits from what you've built.

Reference URLs

  • Subagent specification and AGENT.md fields
  • Memory locations and state management
  • Agent invocation and coordination
  • Tool and permission configuration for agents

Prep Reading

  • What are the most specialized tasks your team does repeatedly?
  • What would an expert in that domain do differently than a generalist?
  • What tools would that specialist need? What tools should they not have?

Notes for Daniel: Subagents might feel advanced, but they're just specialization. Frame it as "hire a specialist." Show a real workflow where a code reviewer agent does its job faster and better than generic Claude because it's optimized for that task. The demo should feel empowering, not complex.