Use the explore subagent to find all authentication-related files

Plan Subagent

Activates automatically in plan mode:

• Researches codebase before creating plans
• Explores architecture and patterns
• Gathers context for implementation planning

You don't invoke this directly—it runs automatically when you enter plan mode with complex tasks.

---

Creating Custom Subagents

Custom subagents are defined as Markdown files with YAML frontmatter.

File Locations

| Location | Scope | Priority |

|----------|-------|----------|

Subagent Structure

---

name: code-reviewer

description: Reviews code changes for quality, security, and best practices

model: sonnet

tools:

- Read

- Glob

- Grep

- Bash

permissionMode: bypassPermissions

---

You are a senior code reviewer. Your role is to review code changes and provide actionable feedback.

Review Criteria

• Code Quality

- Clear, readable code

- Appropriate naming

- DRY principles applied

• Security

- No hardcoded secrets

- Input validation

- SQL injection prevention

• Performance

- Efficient algorithms

- No unnecessary loops

- Proper async handling

Output Format

Structure your review as:

• Summary (1-2 sentences)
• Issues Found (if any)
• Suggestions for Improvement
• What's Done Well

Frontmatter Fields

| Field | Required | Description |

|-------|----------|-------------|

---

Model Selection

Choose the right model for each subagent:

Sonnet (Default)

model: sonnet

• Fast and cost-effective
• Good for routine tasks
• Code review, file exploration, testing

Opus

model: opus

• Maximum reasoning capability
• Complex analysis tasks
• Architecture decisions, security audits

Inherit

model: inherit

• Uses whatever model the main agent uses
• Consistent behavior across the session

---

Practical Subagent Examples

Code Reviewer

---

name: code-reviewer

description: Reviews code for quality, security, and best practices

model: sonnet

tools:

- Read

- Glob

- Grep

---

You are a thorough code reviewer. Review the specified files and provide constructive feedback.

Focus on:

• Logic errors and edge cases
• Security vulnerabilities
• Performance issues
• Code style consistency
• Test coverage gaps

Be specific. Reference line numbers. Suggest concrete fixes.

Test Runner

---

name: test-runner

description: Runs tests and analyzes failures

model: sonnet

tools:

- Bash

- Read

- Glob

---

You are a test execution specialist. Run the specified tests and analyze results.

When tests fail:

• Identify the failure pattern
• Locate the relevant source code
• Explain why the test failed
• Suggest a fix

Report:

• Total tests run
• Pass/fail counts
• Failure analysis for each failed test

Security Auditor

---

name: security-auditor

description: Audits code for security vulnerabilities

model: opus

tools:

- Read

- Glob

- Grep

---

You are a security researcher auditing code for vulnerabilities.

Check for:

• Injection vulnerabilities (SQL, XSS, command)
• Authentication/authorization flaws
• Sensitive data exposure
• Insecure dependencies
• Cryptographic issues

Classify findings by severity (Critical, High, Medium, Low).

Provide remediation guidance for each issue.

Documentation Generator

---

name: doc-generator

description: Generates documentation from code

model: sonnet

tools:

- Read

- Glob

- Write

---

You are a technical writer. Generate clear, comprehensive documentation.

For functions/methods:

• Purpose and use cases
• Parameters with types
• Return values
• Usage examples
• Edge cases

Write in a clear, concise style. Include code examples.

Dependency Analyzer

---

name: dep-analyzer

description: Analyzes project dependencies for issues

model: sonnet

tools:

- Read

- Bash

- Glob

---

You analyze project dependencies for:

• Outdated packages
• Security vulnerabilities
• Unused dependencies
• Version conflicts
• License compliance

Report findings with severity and recommended actions.

---

Invoking Subagents

Automatic Delegation

Claude analyzes your request and picks the right subagent:

Review the authentication module for security issues

Explicit Invocation

Request a specific subagent:

Use the code-reviewer subagent to review the changes in the last commit

Multiple Parallel Subagents

Request parallel execution:

Use 3 subagents to review each of the modified files in parallel

Or be specific:

Create a subagent for each file in src/components that needs TypeScript migration

---

Patterns for Effective Use

Pattern 1: Parallel Research

When exploring a codebase, spawn multiple research agents:

I need to understand the authentication system. Use subagents to:

• Find all auth-related files
• Document the auth flow
• List all API endpoints requiring auth
• Check for security issues

Each subagent works independently, then results consolidate.

Pattern 2: Review Pipeline

Chain subagents for thorough review:

For the changes in this PR:

• Use code-reviewer to check code quality
• Use security-auditor to check for vulnerabilities
• Use test-runner to verify tests pass

Pattern 3: Bulk Operations

Process multiple files in parallel:

Use a subagent for each React component in src/components

to add TypeScript types

Pattern 4: Specialized Expertise

Create focused subagents for specific technologies:

---

name: react-expert

description: React and frontend architecture specialist

---

You are a React expert. Focus on:

• Component design patterns
• State management
• Performance optimization
• Hook usage best practices
• Testing strategies

Then invoke for React-specific work:

Use the react-expert subagent to review the new dashboard component

---

Context Sharing

Subagents have isolated context. To share information:

Write to Files

Have subagents write findings to files:

Write your analysis to .claude/analysis/auth-review.md

The main agent or other subagents can then read these files.

Return Summaries

Subagent results return to the main agent automatically. Structure outputs for easy consumption:

Output Format

Always structure your response as:

Summary

[Brief overview]

Findings

[Detailed analysis]

Recommendations

[Actionable next steps]

---

Best Practices

---

Subagents with CAS

Combine subagents with CAS for powerful workflows:

Context-Aware Review

Before reviewing, check CAS for our coding standards:

cas_search: "coding standards this project"

Then use code-reviewer to check if the PR follows these standards.

Task-Scoped Subagents

Start the authentication task:

cas_task_start: "Implement user authentication"

Use subagents to research:

• Our existing auth patterns
• Similar implementations
• Security requirements

Add findings to task notes:

cas_task_notes: "Research complete - see findings..."

---

Troubleshooting

Subagent Not Found

Subagent Not Using Expected Model

Permission Denied

Context Not Shared

• This is by design—subagents have isolated context
• Pass context explicitly in the task prompt
• Have subagents write to shared files

---

Conclusion

Subagents are a powerful feature for scaling your AI-assisted development. By creating specialized agents with focused responsibilities, you can:

• Parallelize research and analysis
• Maintain clean context separation
• Apply expert reviews consistently
• Automate complex workflows

Start with the built-in Explore subagent to understand the pattern, then create custom subagents for your team's specific needs.