What Are Custom Agents?
When Claude uses the Task tool to spawn subagents, it can use custom agent types that you define. These agents have their own:
- Instructions — What the agent should do and how
- Tool access — Which tools the agent can use
- Model — Which Claude model to use
This lets you create specialized agents for your workflow — a "test runner" agent, a "code reviewer" agent, a "documentation writer" agent, etc.
Opening Agents Settings
- Open Settings (
Cmd+,) - Select "Agents" from the left sidebar
- Choose scope: Global (all projects) or a specific Project
Viewing Agents
The Agents view is a read-only display of all discovered agents. Each agent shows:
- Agent name — The filename without extension
- Model — Which Claude model it uses (shown as a badge)
- Description — What the agent does
- Raw content — Expand to see the full agent file contents
An "Open folder" button lets you jump to the agents directory in your file manager to create or edit agent files.
Global vs Project Agents
- Global agents are available in all projects
- Project agents are only available in that specific project
Creating Custom Agents
Agents are defined as markdown files:
- Global agents:
~/.claude/agents/ - Project agents:
your-project/.claude/agents/
Agent File Structure
Create a .md file (e.g., code-reviewer.md):
---
description: Reviews code changes for best practices and potential issues
tools:
- Read
- Glob
- Grep
model: haiku
---
You are a code review specialist. Review the provided code changes and check for:
1. Security vulnerabilities (OWASP top 10)
2. Performance issues
3. Code style consistency
4. Missing error handling
5. Test coverage gaps
Provide actionable feedback with specific line references.Frontmatter Options
| Field | Description |
|---|---|
description | What the agent does (shown in agent list and Task tool) |
tools | List of tools the agent can access |
model | Which Claude model to use (sonnet, haiku, opus) |
How Agents Are Used
When Claude spawns a subagent using the Task tool, it can specify your custom agent type:
subagent_type: "code-reviewer"The subagent then runs with the instructions and constraints you defined. You'll see it as a Subagent Card in the chat, with the agent type badge colored for easy identification.
Skills
Skills are custom slash commands that extend Claude's capabilities with predefined prompts and instructions. They let you create reusable workflows triggered by a simple `/command`.
Rules
Rules are instruction files that tell Claude how to behave when working on your code. They're the most powerful way to customize Claude's behavior for your specific project and workflow.