Write a Specialist Once, Delegate to It Forever: Custom Subagents in .claude/agents/

Write a markdown file once, and Claude Code delegates matching tasks to your specialist automatically — each invocation runs in its own context window, with only the tools you specified.

Most re-briefing in multi-step Claude Code sessions is wasted effort: "you are a code reviewer, read-only, security focus, return JSON" re-appears in the prompt again and again, burning tokens and producing subtly inconsistent specialists each time. The fix is a file.

The format

Create .claude/agents/code-reviewer.md in your project:

---
name: code-reviewer
description: Reviews changed files for security issues, logic bugs, and API misuse. Read-only — does not edit files. Invoke when asked to review code or before committing.
tools: Read, Grep, Glob
model: sonnet
---
You are a security-focused code reviewer. For each file you review:
1. Check for injection vulnerabilities, unsafe deserialization, and hardcoded credentials
2. Flag API calls where error handling is missing or swallows exceptions
3. Return findings as a JSON array: [{file, line, severity, issue, suggestion}]

Do not edit files. Do not offer praise. List defects only.

Claude Code reads all .claude/agents/ files at startup. When you type "review the auth module before I commit", Claude routes the task to this agent by matching your intent to the description field. The description is what drives routing — write it as a sentence describing what tasks should land here.

Per-project vs per-user

• .claude/agents/ in the repo — checked into git, available to every team member who clones it
• ~/.claude/agents/ in your home directory — follows you across every project you work on

Both coexist. A project-level agent with the same name wins over the user-level one.

The context isolation

Each invocation runs in a fresh context window. Grep results, file reads, and reasoning from the review never appear in your main session — you see only the summary that comes back. This keeps long sessions from degrading and prevents the review's detail noise from influencing your next edits.

The constraint to know

A plain subagent starts with no knowledge of your main session — it sees only the task description you send with the Agent call. If the specialist needs context from earlier in your session (a design decision, a prior finding), pass it explicitly in the task description, or use a fork subagent, which starts from a copy of the current conversation.

Other useful specialists to define: a test-writer (generates pytest from a function signature), a doc-writer (extracts docstrings from a module), a migration-writer (produces Django migrations from model diffs), a dependency-auditor (reads package files and flags known CVEs). Each one costs one markdown file and pays back every session you use it.

Sources: Create custom subagents — Claude Code Docs · How to Build Custom Sub-Agents in Claude Code — MindStudio · Claude Code Subagents and Multi-Agent Orchestration — hidekazu-konishi.com