Write a Custom Claude Code Subagent in 10 Lines: Constrain, Scope, and Auto-Delegate Specialists

A .claude/agents/ Markdown file with five frontmatter fields creates a reusable, model-constrained specialist Claude delegates to automatically — no per-task prompting, no context overflow.

The built-in subagents — Explore, Plan, and general-purpose — cover most delegation patterns, but once you find yourself repeatedly typing the same context ("you are a read-only reviewer who...") you're leaving a custom subagent on the table.

The file format

---
name: doc-reviewer
description: Reviews docs, README files, and docstrings for clarity and completeness. Use proactively whenever documentation quality is in question.
tools: Read, Grep, Glob
model: haiku
---

You are a technical writing reviewer. For each file you review:
- Flag unclear descriptions and suggest rewrites
- Check that all public APIs have docstrings
- Mentally trace code examples to verify they compile

Return a bulleted list of issues, not prose. Be brief.

Save to .claude/agents/doc-reviewer.md in your project (or ~/.claude/agents/ for a user-level agent available everywhere). Done.

Why each field matters

name — The identifier; also how you request it manually ("use the doc-reviewer agent").

description — The delegation signal. Claude reads this to decide when to automatically hand off a task. Write it behaviorally: "Use when asked to X" or "Triggers when documentation quality is in question." Vague descriptions make Claude guess wrong.

tools — Constrain to exactly what the job needs. A read-only reviewer doesn't need Bash or Edit. Narrower tool sets also let you trust the output more — if a reviewer can only Read, it can't accidentally modify anything.

model: haiku — Route mechanical tasks (formatting checks, doc reviews, log summarization) to Haiku. This is the same model-tiering trick from cost control, baked into the agent file so it's enforced automatically.

The system prompt (rest of the file) — What the agent does when delegated to. Keep it focused: one job, clear output format.

Project vs. user scope

.claude/agents/ is committed alongside your code — it ships your team's shared specialists with the repo and appears in every collaborator's session. ~/.claude/agents/ is personal and available in every project on your machine. When both define an agent with the same name, the project version wins.

Three subagents worth building today

Security scanner — tools: Read, Grep, Bash, model: sonnet, prompt: check changed files for hardcoded credentials, SQL injection risks, and missing input validation; return findings as a JSON array.

Test gap finder — tools: Read, Glob, Grep, model: haiku, prompt: list functions and methods in changed files that have no corresponding test coverage; be concise.

Changelog writer — tools: Read, Bash (for git log), model: haiku, prompt: draft a CHANGELOG entry from the last N commits in Keep a Changelog format.

Each of these keeps its work in its own context window, so search results and file trees never flood your main session. And because the model and tool constraints are in the file, they're consistent whether you invoke them manually or Claude delegates automatically.

Sources: Create custom subagents — Claude Code Docs · Built-in subagents reference · Manage costs — Claude Code Docs