Custom Agents

Agent structure

An agent is a Markdown file placed in .claude/agents/ with a YAML frontmatter. Claude Code discovers it automatically at session startup.

---
name: code-reviewer
description: Use to review code before any commit
model: sonnet
tools: Read, Grep, Glob
memory: project
---

The file body contains instructions in Markdown: role, methodology, examples, constraints.

Frontmatter fields

The tools field: isolation by default

Limiting tools to what the agent actually needs reduces the exposure surface and accidental errors. A code review agent only needs Read, Grep, Glob — no reason to give it Bash or Write.

Persistent memory (v2.1.32+)

memory: project   # .claude/agent-memory/<name>/
memory: user      # ~/.claude/agent-memory/<name>/
memory: local     # .claude/agent-memory-local/<name>/

project memory is committed with the repo — useful for the agent to accumulate knowledge shared across the entire team. local memory stays private to the machine.

Agent vs Slash Command

Create an agent when the task recurs regularly with stable context and tools. Create a command when it is a one-off workflow or a procedure to follow.

Concrete example: code review agent

---
name: code-reviewer
description: Use PROACTIVELY after every code modification
  to verify quality, security, and conventions
model: sonnet
tools: Read, Grep, Glob
memory: project
---

# Code Reviewer

Systematically verify: OWASP security, test coverage,
project convention compliance, and introduced technical debt.

The keyword PROACTIVELY in the description encourages Claude to invoke the agent without waiting for an explicit request.