Custom Agents
Foundation → Sub-Agents covered the built-in agent types (Explore, Plan, general-purpose, claude-code-guide, statusline-setup) — the workhorses Claude Code ships with. This page is about writing your own: project-specific specialists like a code-reviewer that knows your standards, a security-auditor for your threat model, a test-writer that matches your framework.
Custom agents use the same isolation mechanics as the built-ins — fresh context window, summary-only return, depth-limited to one level. The difference is authorship. You define them as markdown files in .claude/agents/ and commit them to git, so everyone on the team inherits the same specialists on clone.
| Skills | Custom Agents | |
|---|---|---|
| What they are | Directory-based packages (SKILL.md + templates, scripts, reference files) | Single .md file defining a specialist worker |
| Context | Shares your session | Fresh, isolated — cannot see your conversation |
| Best for | Reusable workflows, slash commands | Deep analysis, code review, security audit |
| Invoked by | You type /skill-name | Claude spawns them via the Agent tool |
| Think of it as | A toolkit you use at your desk | A specialist contractor you send on a mission |
An agent file lives in .claude/agents/ and has two parts: YAML frontmatter that configures the agent's behavior (tools, model, permissions), and a markdown body that serves as the agent's system instructions. Let's create one.
The agent you just created used name, description, and tools. Here is the full set of frontmatter fields:
| Field | Purpose | Example |
|---|---|---|
name | Display name in logs and parent context | code-reviewer |
description | When to trigger this agent — helps the Agent tool match context | "Triggered for PR reviews" |
tools | Allowlist of tools the agent can use (least privilege) | [Read, Glob, Grep] |
disallowedTools | Denylist — block specific tools instead of allowlisting | [Bash, Write] |
model | Claude model to use: sonnet, haiku, opus, full ID, or inherit | sonnet |
effort | Reasoning effort: low, medium, high, xhigh, max | high |
permissionMode | default, acceptEdits, auto, dontAsk, bypassPermissions, plan | bypassPermissions |
maxTurns | Maximum agentic loop iterations before forced stop | 10 |
memory | Persistent memory tier: user, project, or local | project |
skills | Skills injected into the agent's context at startup | [tdd-workflow] |
mcpServers | MCP servers available to this agent | [github, jira] |
hooks | Agent-specific hook overrides | (hook config object) |
background | Always run as a background task | true |
isolation | Run in a temporary git worktree (edits never conflict) | worktree |
color | Display color in the UI | blue |
The key design principle: least privilege. Give each agent only the tools it needs. A code-reviewer needs Read, Glob, Grep — not Write, Edit, or Bash. The isolation mechanics (fresh context, summary-only return, depth=1) work the same way as the built-in sub-agents covered in Foundation.
| Pattern | How it works | Use case |
|---|---|---|
| Background execution | Agent runs in background while you keep working. /agents to list, resume by ID. | Long-running reviews, bulk analysis |
| Persistent memory | memory: project — agent reads/writes shared MEMORY.md across sessions. | Recurring audits, cross-session knowledge |
| Worktree isolation | isolation: worktree — agent gets its own git worktree. Edits never conflict with yours. | Parallel agents that all edit code, safe prototyping |
| Agent resume | /agents lists all agents. Resume any by ID to check progress or retrieve results. | Monitor background agents, get partial results |
A mature project typically has 3–6 agents covering different domains:
| Agent File | Description |
|---|---|
code-reviewer.md | Senior Engineer — correctness, patterns, naming, edge cases. Tools: Read, Glob, Grep. |
security-auditor.md | AppSec Specialist — OWASP Top 10, injection, auth, secrets. Tools: Read, Glob, Grep. |
test-writer.md | QA Engineer — unit tests, edge cases, mocking strategy. Tools: Read, Glob, Grep, Edit, Write. |
architecture-reviewer.md | Systems Architect — design patterns, scalability, ADR compliance. Tools: Read, Glob, Grep. |
Each agent is committed to git. When a new developer joins the team, they inherit the full agent library on first clone.