Define Once, Reuse Everywhere: Build Specialized Subagents with .claude/agents/*.md

Drop a markdown file in .claude/agents/ to give Claude Code a permanent, specialized collaborator — scoped tools, a custom model, and a tailored system prompt that fires by description match or explicit @-mention.

The default Claude Code agent is a generalist with full tool access. That's great for open-ended work, but a liability when you want a reviewer that can never accidentally edit files, or a doc writer that only touches Markdown. Custom subagent definitions solve this cleanly.

Create .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use to review code changes for correctness, bugs, style, and security. Invoke when asked to review a diff or check a PR.
model: claude-haiku-4-5-20251001
tools:
  - Read
  - Glob
  - Grep
---

You are a senior code reviewer. Review the code changes passed to you and report:
1. Bugs or logic errors (file + line number)
2. Security issues (injection, auth bypass, data exposure)
3. Style violations against project conventions
4. Suggestions for simplification

Be specific and concise. Return findings as a numbered list. Never edit files.

Invoke it

# Claude picks it by description match
Review the changes in app/auth/

# Or force it with an explicit @-mention
@code-reviewer check the diff in src/api.ts

The fields that matter

• model — run Haiku for reviewer/summarizer tasks that don't need frontier intelligence. Save Opus/Sonnet for the orchestrator. Per-agent model tiering is one of the biggest levers for cost control.
• tools — least privilege: Read, Glob, Grep block any writes. A misconfigured orchestrator cannot accidentally trigger an edit through this agent.
• description — this is what Claude uses for auto-invocation. Be specific and keyword-rich; vague descriptions get ignored and the agent never fires automatically.

Scope: project vs global

Location	Scope
.claude/agents/	This repo only
~/.claude/agents/	Every project on this machine

Project agents override global ones with the same name. A code-reviewer.md in the repo takes precedence over a global one, which is handy for project-specific conventions.

Other useful subagent patterns

A test-writer.md with only Write + Read (no Bash) keeps it from running tests itself. A researcher.md with WebSearch + Read (no file writes) isolates web access to one scoped agent. A sql-analyst.md with only the Postgres MCP tool gates database access to a single named agent.

Sources: Create custom subagents — Claude Code Docs · Claude Code Subagents: Complete Guide (Ivern AI)