Custom agents are persistent subagent definitions stored as Markdown files in .claude/agents/. The official documentation calls all of these “subagents” — we use “custom agents” here to distinguish file-based, reusable definitions from the temporary subagents Claude spawns dynamically for one-off tasks. Both are configured the same way; the difference is persistence and intent.
Each agent gets its own system prompt, tool set, model selection, and permission mode. When you or Claude invokes an agent, it runs in its own context with only the capabilities you’ve defined.
Creating an agent
Using /agents (recommended)
Run /agents in Claude Code to create, edit, and manage agents interactively. Choose “Create new agent” → select scope (Personal or Project) → describe what the agent should do. Claude generates the configuration.
Manual file creation
Create a Markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal):
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a senior code reviewer. Analyze code for:
- Security vulnerabilities
- Performance issues
- Readability and maintainability
- Test coverage gaps
Provide specific, actionable feedback with code examples.Supported frontmatter fields
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier (lowercase, hyphens) |
description | Yes | When Claude should delegate to this agent |
tools | No | Tools the agent can use (inherits all if omitted) |
disallowedTools | No | Tools to deny |
model | No | sonnet, opus, haiku, or inherit |
permissionMode | No | default, acceptEdits, plan, auto, dontAsk, bypassPermissions |
maxTurns | No | Maximum agentic turns before stopping |
isolation | No | Set to worktree for isolated file system |
color | No | Background color in the UI |
memory | No | user, project, or local for persistent memory |
skills | No | Skills loaded into the agent’s context |
mcpServers | No | MCP servers available to this agent |
hooks | No | Lifecycle hooks scoped to this agent |
effort | No | Thinking effort level: low, medium, high, max |
background | No | Run the agent in the background |
initialPrompt | No | First prompt sent automatically when the agent starts |
Agent scope and priority
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Organization-wide | Highest |
--agents CLI flag | Current session only | High |
.claude/agents/ | Current project | Medium |
~/.claude/agents/ | All your projects | Lower |
| Plugin agents/ | Where plugin is enabled | Lowest |
When multiple agents share the same name, the higher-priority location wins.
Launching agents
From the CLI:
claude --agent code-reviewerDuring a session, run /agents to see available agents or ask Claude directly — it delegates based on the agent’s description.
For one-off agent definitions without saving files:
claude --agents '{"reviewer": {"description": "Code reviewer", "prompt": "You review code.", "tools": ["Read", "Grep"], "model": "sonnet"}}'Custom agents vs subagents
| Custom Agents | Subagents | |
|---|---|---|
| Defined in | .claude/agents/*.md files | Spawned dynamically by Claude |
| Persistence | Permanent, version-controlled | Temporary, single-task |
| Configuration | Full frontmatter (tools, model, hooks, MCP) | Inherited from parent with optional overrides |
| Use case | Recurring roles (reviewer, debugger, architect) | One-off parallel investigations |
Example agents
Read-only analyst
---
name: analyst
description: Analyzes code patterns and architecture without making changes
tools: Read, Glob, Grep, Bash
model: haiku
---
You are a read-only code analyst. Never suggest edits directly.
Analyze patterns, dependencies, and architecture. Report findings clearly.Build validator
---
name: build-validator
description: Validates that the project builds and tests pass
tools: Bash, Read
model: sonnet
---
Run the build and test suite. Report any failures with file paths and line numbers.
Do not fix issues — only report them.
Commands to run:
1. npm run build
2. npm testSecurity auditor
---
name: security-auditor
description: Scans code for security vulnerabilities
tools: Read, Glob, Grep
model: opus
permissionMode: plan
---
You are a security auditor. Scan for OWASP Top 10 vulnerabilities:
- SQL injection, XSS, CSRF
- Hardcoded secrets and credentials
- Insecure dependencies
- Missing input validation
Report severity (Critical/High/Medium/Low) with specific file locations.Tips
- Start with read-only agents (restrict tools to Read, Glob, Grep) for safety.
- Use
model: haikufor fast agents that don’t need deep reasoning. - Set
isolation: worktreewhen agents need to make experimental changes. - Check project agents into version control so the whole team benefits.
- Write clear descriptions — Claude uses them to decide when to delegate.