Claude Code subagents, six specialists deep.
A code reviewer that must attach a failure scenario to every finding. A security auditor that thinks in attack scenarios. A refactor planner that only ships revertable steps. Six specialist agents from our client work, plus the subagents documentation people actually search for.
Six specialists, opinionated on purpose.
| Agent | Writes files? | What it does |
|---|---|---|
| code-reviewer | No | Bugs, edge cases, design problems; every finding carries a failure scenario |
| security-auditor | No | Injection, IDOR, secrets, SSRF, CORS/CSRF, with attack scenarios and fixes |
| perf-auditor | No | Evidence-first performance findings ranked by user-felt cost |
| test-writer | Yes | Behavior-driven tests in your project’s style; red-green bug repros |
| docs-writer | Yes | References, guides, and ADRs verified against the actual code |
| refactor-planner | No | Turns a scary refactor into safe, shippable, revertable steps |
The auditors deliberately carry no Write or Edit tools: their report is the product, and a reviewer that cannot touch code cannot break it. Each agent is one readable markdown file.
A separate context window is the point.
A real review reads a lot: the diff, the full files around it, the callers, sometimes the tests. Do that in your main session and the investigation itself eats the context you were working in. A subagent runs in its own window: it reads everything it needs over there, and only the report comes home. Delegation is a context-budget strategy, not a gimmick.
Anatomy, from this pack’s reviewer:
--- name: code-reviewer description: Reviews a diff, branch, or PR for bugs, edge cases, and design problems before merge. Use proactively after completing a feature, or when the user asks for a review. tools: Read, Grep, Glob, Bash model: inherit --- You are a senior code reviewer. You review changes, you do not rewrite them. Process: 1. Establish the diff under review and read every changed hunk in the context of its full file... 2. Trace each behavior change to its callers. Grep for them; do not assume. ...
Only name and descriptionare required; the body below the frontmatter is the agent’s entire system prompt. The description drives auto-delegation, so it says when to use the agent, not what it is.
How to install and use them.
Unzip, copy into your repo (or ~/.claude/agents/ for all projects):
your-repo/
└── .claude/
└── agents/
├── code-reviewer.md
├── security-auditor.md
├── perf-auditor.md
├── test-writer.md
├── docs-writer.md
└── refactor-planner.mdNew session, then ask naturally: “review this branch before I open the PR”, “plan the extraction of the billing module”. Claude matches the request to a description and delegates. To force a specific agent, @-mention it: @security-auditor check the new upload endpoint.
Frontmatter fields that matter.
| Key | Effect |
|---|---|
name / description | Required; description drives auto-delegation |
tools | Allowlist; omit for all tools. Read-only agents = safer reviewers |
model | Pin a model, or inherit to match the session |
maxTurns | Hard cap on agentic turns; the runaway brake |
permissionMode | Per-agent permission behavior (e.g. plan-only) |
memory | Persistent memory scope across runs (user / project / local) |
Common questions.
01What are subagents in Claude Code?
A subagent is a separate Claude instance with its own system prompt, its own tool permissions, and crucially its own context window. Your main session delegates a job ("review this branch"), the subagent does the whole investigation in its private context, and only the final report comes back. Big jobs stop flooding your session.
02How do I create a subagent in Claude Code?
Create a markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal). YAML frontmatter needs just name and description; everything below the frontmatter becomes the agent’s system prompt. Optional keys worth knowing: tools to allowlist what it may touch, model to pin a cheaper or stronger model, maxTurns to cap runaway sessions. The six files in this pack are complete worked examples.
03How do I use subagents once installed?
Ask naturally: Claude reads each agent’s description and delegates when your request matches ("audit the upload endpoint for security holes" routes to the security auditor). To force a specific one, @-mention it: @code-reviewer look at the last two commits. Each run returns a report into your main conversation.
04Why do the reviewer agents have no Write or Edit tools?
Deliberate design. A reviewer that can edit will eventually "helpfully" fix what it reviews, which destroys the independence that makes a review worth having, and a compromised or confused reviewer with write access is a hazard. Its tools line grants Read, Grep, Glob, Bash only; the report is its output. The test-writer and docs-writer, whose job is producing files, do get write access.
05What is the difference between subagents and skills?
A skill is instructions loaded into your current session; a subagent is a separate worker with its own context. The practical rule: workflows you want inline (commit message, changelog) are skills; investigations that produce a report (review, audit, refactor plan) are subagents, because their reading does not consume your session context.
06Can I change which model a subagent uses?
Yes: the model frontmatter key takes a model name or inherit (use whatever the main session runs). These six ship with inherit. A common tweak is pinning mechanical agents to a fast cheap model while your session runs a stronger one.
- Claude Code skills packTen ready-made skills, plus the install and activation guide people actually search for.Free · 10 skills
- Claude Code hooks packEight production-grade hooks with the missing documentation: events, stdin payloads, exit codes.Free · 8 hooks
- CLAUDE.md templatesFive battle-tested CLAUDE.md files: Next.js, Python, monorepo, API service, and a lean starter.Free · 5 templates
- Claude Code statuslineA one-file statusline showing model, git branch, context left and session cost. Paste, done.Free · 1 script
Want agents that know your architecture?
The generic six are free. The valuable ones are bespoke: a reviewer that knows your API conventions, an auditor tuned to your compliance reality, a planner that respects your deploy windows. That is client work we love. techpotions is a small studio; you talk to the people who build.