Claude Code /agents Explained: Custom AI Sub-Agents, Each with Their Own Role

Why You Need /agents

If you’ve used Claude Code for development, you’ve probably seen the Agent tool in action — Claude automatically spawns a “sub-agent” to search code, read files, or handle sub-tasks.

But have you ever wondered: Who are these sub-agents? What can they do? Can you define your own?

Consider these real scenarios:

• You want Claude to explore an unfamiliar codebase, but don’t want it editing files while browsing
• You want Claude to plan an architecture, but don’t want it to skip planning and jump straight to coding
• You want a “test expert” that only runs tests and analyzes failures, never touching business code
• Your team has specific code review rules and you want Claude to follow them exactly

The default general-purpose sub-agent can’t do all of this. What you need is: specialized Agents for different tasks.

That’s the value of /agents.

What Is /agents

/agents is Claude Code’s Agent management command. Type it and you’ll see a list of all available Agents, both built-in and custom.

In interactive mode, type:

/agents

An interactive menu appears, listing all Agents grouped by source (built-in, project, user, plugin), showing each Agent’s description, available tools, and model configuration.

Built-in Agents

Claude Code ships with several built-in Agents that work out of the box:

general-purpose

This is the default sub-agent, used when no subagent_type is specified.

• What it can do: Almost everything — search code, read/write files, run commands, use all tools
• Tool access: * (all tools)
• Model: Sonnet by default (sub-agents use faster models to save cost)
• Best for: General tasks, multi-step operations, when you’re not sure which Agent to use

Explore

A read-only Agent designed for quickly understanding a codebase.

• What it can do: Search files, read code, analyze structure
• What it can’t do: No file editing, no file writing, no spawning sub-agents
• Model: Haiku (fast and cheap)
• Special: Skips loading CLAUDE.md for faster startup and cleaner context
• Best for: Quick keyword searches, understanding file structure, answering “where is this code” questions

Plan

A read-only Agent designed for architecture planning.

• What it can do: Read code, analyze architecture, design implementation plans
• What it can’t do: No file editing, no file writing, no spawning sub-agents
• Model: Inherits the parent model (usually Opus)
• Special: Read-only but does deep analysis, suited for tasks that need careful thinking
• Best for: Designing implementation plans, evaluating architecture trade-offs, analyzing critical files

These built-in Agents cover the most common development patterns: general work, quick lookup, deep planning.

Custom Agents

When built-in Agents don’t meet your needs, you can create your own.

How to Create One

A custom Agent is simply a Markdown file placed in the .claude/agents/ directory:

# Project-level Agent (shared with all collaborators)
.claude/agents/my-agent.md

# User-level Agent (only available to you)
~/.claude/agents/my-agent.md

The file structure is simple: YAML frontmatter + system prompt.

Full Example: Test Expert

---
name: test-expert
description: Run tests, analyze failures, suggest fixes without touching business code
model: sonnet
tools: [Bash, Read, Glob, Grep]
disallowedTools: [Edit, Write]
---

You are a testing specialist. Your job is to:

1. Run the test suite using the project's test command
2. Analyze any test failures in detail
3. Read the relevant source code to understand the failure
4. Suggest specific fixes, but NEVER modify files yourself

Always report:

- Which tests failed and why
- The root cause (not just the symptom)
- A concrete fix suggestion with code snippets

Save this as .claude/agents/test-expert.md, and Claude can invoke it via the Agent tool:

Run the tests using the test-expert agent

Claude will automatically use subagent_type: "test-expert" and follow your defined rules.

Configuration Reference

Fields available in the frontmatter:

Field	Description	Example
name	Agent name	test-expert
description	Description (determines when Claude uses it)	Run and analyze tests
model	Model to use	opus, sonnet, haiku, inherit
tools	Tool allowlist	[Bash, Read, Glob, Grep]
disallowedTools	Tool denylist	[Edit, Write, Agent]
maxTurns	Maximum conversation turns	200
memory	Persistent memory scope	user, project, local
isolation	Isolation mode	worktree
background	Run in background by default	true
permissionMode	Permission mode	plan, acceptEdits, bubble
mcpServers	Required MCP servers	[slack]

Key configuration details:

model: inherit: Inherits the parent conversation’s model. If your main conversation uses Opus, the sub-agent uses Opus too.

isolation: worktree: Runs in an isolated git worktree. All file operations happen in a separate copy, leaving your working directory untouched. If the Agent makes no changes, the worktree is automatically cleaned up; if it does, the branch and path are preserved for your review.

permissionMode: Controls the Agent’s permission behavior. plan means read-only, acceptEdits means auto-accept edits, bubble means permission requests bubble up to the parent.

memory: Gives the Agent persistent memory. Set to project and the Agent will remember project context across sessions.

Practical Agent Examples

Code Reviewer

---
name: reviewer
description: Review code changes for quality, security, and best practices
model: opus
tools: [Bash, Read, Glob, Grep]
disallowedTools: [Edit, Write, Agent]
---

You are a senior code reviewer. Review the current diff and check for:

1. Logic errors and edge cases
2. Security vulnerabilities (OWASP Top 10)
3. Performance issues
4. Code style violations
5. Missing error handling

Be specific: cite file paths and line numbers. Rate severity as critical / warning / suggestion.

Documentation Syncer

---
name: doc-sync
description: Update documentation to match code changes
model: sonnet
tools: [Read, Write, Edit, Glob, Grep]
disallowedTools: [Bash, Agent]
---

You are a documentation specialist. Your job is to:

1. Read the recent code changes (git diff)
2. Find all related documentation files
3. Update docs to reflect the code changes
4. Ensure README, API docs, and inline comments are in sync

Never run commands. Only read code and update docs.

Isolated Experimenter

---
name: experiment
description: Try experimental changes in an isolated worktree
model: opus
isolation: worktree
background: true
---

You are an experimental agent. You work in an isolated git worktree,
so your changes won't affect the main working directory.

Try the approach described in the prompt. If it works, report the
worktree path and branch name so the user can review and merge.
If it fails, explain why and suggest alternatives.

Agent Priority

When Agents with the same name exist in multiple sources, Claude Code picks by priority (highest to lowest):

1. User-level — ~/.claude/agents/
2. Project-level — .claude/agents/
3. Plugin — Agents loaded via plugins
4. Built-in — Claude Code’s built-in Agents

This means you can “override” a built-in Agent’s behavior with a same-named file. For example, creating ~/.claude/agents/general-purpose.md lets you customize the default sub-agent’s behavior.

Agent vs. Skills

At first glance, Agents and Skills look similar — both are Markdown files that customize behavior. But they solve fundamentally different problems:

	Agent	Skill
Nature	Independent AI role	Prompt template
Execution	Subprocess with its own context	Expands in current conversation
Tool access	Configurable (allowlist/denylist)	Inherits current conversation’s permissions
Model	Can use a different model	Uses current conversation’s model
Isolation	Supports worktree isolation	No isolation
Best for	Sub-tasks needing independent execution	Reusable prompt patterns

Simple rule: If you just want to reuse a prompt, use a Skill. If you need an independent AI role with its own permissions and tool restrictions to execute a sub-task, use an Agent.

Background Agents

Agents can run in the background without blocking your main conversation.

Two ways to enable this:

1. In the Agent definition: background: true
2. At invocation time: Claude sets run_in_background: true in the Agent tool

After a background Agent launches, you can continue chatting with Claude. When the Agent finishes, you’ll be notified automatically. Use the /tasks command to check the status of all background Agents.

Tips

1. Write a Good Description

Claude decides which Agent to use primarily based on the description field. The more precise it is, the better Claude picks the right Agent automatically.

# Too vague
description: Helper agent

# Precise
description: Run and analyze test failures, suggest fixes without modifying code

2. Minimize Tool Permissions

Give an Agent only the tools it needs to do its job. A read-only exploration Agent doesn’t need Write and Edit. A documentation Agent doesn’t need Bash.

3. Use Worktree Isolation

For experimental changes, set isolation: worktree. Even if the Agent breaks something, your working directory stays clean.

4. Share with Your Team

Put Agent definitions in .claude/agents/ and commit them to Git. The whole team shares the same set of Agent roles. It’s a great way to standardize how your team uses AI.

Final Thoughts

The core idea behind /agents is role specialization.

A general-purpose Agent can do everything but excels at nothing. Custom Agents let you create specialized roles for different tasks — some read-only, some focused on testing, some experimenting in isolation.

Just like a team with frontend, backend, QA, and architects — each with their own responsibilities and permissions — Claude Code’s Agent system lets you manage AI assistants with the same mindset.

Defining reusable Agent roles is far more efficient than describing them in natural language every time.