Custom Agents

Working Code

Let's create a code review specialist agent in the .claude/agents/ directory:

> Create .claude/agents/code-reviewer.md with this content:

---
name: code-reviewer
description: Code review specialist. Reviews quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer.

## Review Procedure

1. Check changes with `git diff`
2. Analyze type safety, error handling, and performance
3. Check for security vulnerabilities
4. Verify coding convention compliance

## Output Format

For each file:

- [Pass] or [Issue]
- If there's an issue, provide specific improvement suggestions
- Severity: High/Medium/Low

Verify the agent is registered. Type /agents in your session:

> /agents

Now modify some code and request a review:

> @code-reviewer Review the code I just changed

Claude runs the code-reviewer agent as a sub-agent.

Try It Yourself

Create a documentation specialist agent too:

> Create .claude/agents/doc-writer.md with this content:

---
name: doc-writer
description: Specialist in writing API documentation and READMEs.
tools: Read, Grep, Glob, Write
model: inherit
---

You are a technical documentation specialist.

## Documentation Rules

- Add JSDoc/TSDoc comments to all public functions
- Include installation, usage, and API reference in README.md
- Code examples must be runnable
- Write in English

Run the agent in the background:

> @doc-writer Write API documentation for this project

Press Ctrl+B during execution to move it to the background. Continue with other work in the main prompt. You can check the results when the agent completes.

"Why?" — Specialized Roles Produce Better Results

Assigning specialized roles produces better results than generic prompts. Here's why:

1. Role-appropriate perspective: A code reviewer focuses on security and quality; a documentation writer focuses on readability and completeness.
2. Tool restrictions: Allowing only necessary tools prevents unnecessary actions.
3. Parallel processing: Run multiple agents simultaneously to save time.

Agent Definition Structure

---
name: agent name
description: role description (used for matching)
tools: list of allowed tools
model: inherit or sonnet, opus, haiku
permissionMode: default
---

System prompt content

permissionMode controls the agent's permissions:

| Mode | Behavior | | ------------------- | ------------------------------------------------------- | | default | Asks user for approval when needed | | dontAsk | Auto-rejects approval prompts (only allowed tools work) | | bypassPermissions | Skips all permission checks (use with caution) | | plan | Read-only exploration only |

Agent Storage Locations

| Location | Scope | | ------------------- | -------------------------------- | | .claude/agents/ | Project-specific (commit to Git) | | ~/.claude/agents/ | Shared across all projects |

Useful Agent Patterns in Practice

| Agent | Role | | ------------------ | ---------------------------------- | | code-reviewer | Review code changes | | doc-writer | Write API docs, READMEs | | test-writer | Generate unit/integration tests | | security-auditor | Check for security vulnerabilities | | refactorer | Clean up code, improve patterns |

Calling Sub-Agents

@agent-name task instructions

Using @ calls the agent as a sub-agent. Sub-agents work in their own context, separate from the main session, and return only the results.

Deep Dive