Custom Subagents & /agents

Specialized agents with their own context

Subagents are workers with their own context window, tool allowlist, and system prompt. The parent Claude delegates a scoped task; the subagent works in isolation; the parent gets back the result without polluting its own context. This is how you tackle large jobs without blowing the main session's budget.

Three built-ins ship out of the box: Explore (fast, read-only, runs on Haiku — the right tool for "where is X defined across this repo?"), Plan (Sonnet/Opus, gathers context and produces an implementation plan before code is touched), General-purpose (full tools, used for parallel implementation work).

Custom subagents are markdown files with YAML frontmatter — same shape as Skills but with their own config knobs: tools: allowlist, tool_denylist:, model: override, memory: always-loaded context, worktree: true for filesystem isolation. They live in .claude/agents/ (project), ~/.claude/agents/ (user), or via --agents JSON at launch. /agents opens the interactive manager.

Code

A read-only security agent·markdown

---
name: security-reviewer
description: >
  Security code review. Auto-delegated when reviewing auth,
  payments, or data-handling code. Reads only, never edits.
model: claude-opus-4-7
tools:
  - Read
  - Grep
  - Glob
  - Bash(grep *)
  - Bash(find *)
  - WebFetch(domain:owasp.org)
tool_denylist:
  - Edit
  - Write
  - Bash(git *)
memory: |
  Audit-only. Never modify files. Always cite the CWE class
  for each finding. OWASP Top 10 is the floor, not the ceiling.
worktree: false
---

You are a senior application security engineer. Produce:
1. Executive summary (1 paragraph)
2. Critical findings (CVSS ≥ 7.0)
3. Medium findings (CVSS 4.0–6.9)
4. Low / informational
5. Remediation priority matrix

Parallel team for a refactor·bash

# In an interactive session
"Refactor the entire payment module:
 - Spawn the security-reviewer to audit the current code
 - Spawn db-migration-agent to update the Prisma schema
 - Spawn a general-purpose agent for the API layer
 Work in parallel, then consolidate."

# Each subagent runs with its own context window in its own worktree
# Parent Claude gets summaries back and orchestrates

Custom Subagents & /agents

Specialized agents with their own context

Code

External links

Exercise

Progress

Comments 0