Skip to main content

Subagents

A subagent is a specialised assistant that works in its own context window.

The subagent can:

  • Search many files without filling the main conversation
  • Perform focused research
  • Review security or test coverage
  • Use a restricted tool set
  • Apply a specialised system prompt
  • Return only the relevant summary

Subagents are useful when a side task would otherwise fill the main session with logs, search results, or large file contents.

Create a custom subagent​

Create:

.claude/agents/security-reviewer.md

Add:

---
name: security-reviewer
description: Review code changes for application security risks
tools: Read, Grep, Glob
---

You are a read-only application security reviewer.

Review the requested code or Git diff for:

- Input validation weaknesses
- Authentication and authorisation defects
- Injection risks
- Secret exposure
- Unsafe file access
- Insecure network communication
- Sensitive data leakage
- Missing security tests

Do not edit files.

Return:

1. Critical findings
2. High findings
3. Medium findings
4. Low findings
5. Recommended validation steps

Ask Claude to use the subagent​

Use the security-reviewer subagent to review the current uncommitted changes.

Return only the findings and recommended validation steps.
Do not modify files.

Code reviewer​

Reviews correctness, maintainability, complexity, and consistency without modifying files.

For: Read-only review

Test analyst​

Identifies missing scenarios, edge cases, weak assertions, and regression risks.

For: Quality assurance

Security reviewer​

Examines changes for common security risks and recommends focused validation.

For: Security validation

Documentation analyst​

Identifies documentation impact and drafts concise updates for affected behavior.

For: Documentation quality

Keep permissions focused​

A subagent should receive only the tools required for its role.

Examples:

  • A reviewer normally needs Read, Grep, and Glob
  • A test runner may require Bash but not file-editing tools
  • A documentation agent may need Read and Write for specific directories
  • A research agent should not receive deployment or production-write access
Start with read-only subagents

Create review and analysis subagents before creating agents that can modify code or execute commands. Read-only roles are easier to validate and govern.

Hooks and subagents checkpoint

Continue after configuring one safe hook, verifying the hook through the hooks interface, creating one read-only subagent, and reviewing the subagent output for scope, accuracy, and unnecessary access.