Custom Agent Definitions
Expert knowledge for defining and configuring custom agents in Claude Code.
Core Concepts
Custom Agents allow you to define specialized agent types beyond the built-in ones (Explore, Plan, Bash, etc.). Each custom agent can have its own model, tools, and context configuration.
Agent Definition Schema
Custom agents are defined in .claude/agents/ or via plugin agent directories.
Basic Structure
name: my-custom-agent description: What this agent does model: sonnet allowed-tools: Bash, Read, Grep, Glob
Agent System Prompt
Instructions and context for the agent...
Context Forking
The context field controls how the agent's context relates to the parent conversation:
Value Behavior
fork
Creates an independent context copy - agent sees parent history but changes don't affect parent
(default) Agent shares context with parent and can see/modify conversation state
Example: Isolated Research Agent
name: research-agent description: Research questions without modifying main context model: sonnet context: fork allowed-tools: WebSearch, WebFetch, Read
Research Agent
You are a research specialist. Search for information and provide findings. Your research doesn't affect the main conversation context.
When to use context: fork :
-
Exploratory research that shouldn't pollute main context
-
Parallel investigations with potentially conflicting approaches
-
Isolated experiments or testing
-
Background tasks that run independently
Agent Field for Delegation
The agent field specifies which agent type to use when delegating via the Agent tool:
name: code-review-workflow description: Comprehensive code review agent: security-auditor allowed-tools: Read, Grep, Glob, TodoWrite
This allows commands and skills to specify a preferred agent type for delegation.
Disallowed Tools (Restrictions)
The disallowedTools field explicitly prevents an agent from using certain tools:
name: read-only-explorer description: Explore codebase without modifications model: haiku allowed-tools: Bash, Read, Grep, Glob disallowedTools: Write, Edit, NotebookEdit
Read-Only Explorer
Explore and analyze code. Do not make any modifications.
Disallowed Tools vs Allowed Tools:
Field Purpose Behavior
allowed-tools
Whitelist of permitted tools Agent can ONLY use these tools
disallowedTools
Blacklist of forbidden tools Agent can use all tools EXCEPT these
When to use disallowedTools :
-
Creating read-only agents that can explore but not modify
-
Restricting dangerous capabilities (Bash execution)
-
Sandboxing agents for specific tasks
-
Security-sensitive contexts
Complete Example
name: security-auditor description: Security-focused code review agent model: sonnet context: fork allowed-tools: Read, Grep, Glob, WebSearch, TodoWrite disallowedTools: Bash, Write, Edit created: 2026-01-20 modified: 2026-01-20 reviewed: 2026-01-20
Security Auditor Agent
You are a security auditor. Analyze code for vulnerabilities.
Capabilities
- Read and analyze source code
- Search for security patterns
- Research known vulnerabilities
- Track findings in todo list
Restrictions
- Cannot execute code (no Bash)
- Cannot modify files (no Write/Edit)
- Work in isolated context
Focus Areas
- SQL injection vulnerabilities
- XSS vulnerabilities
- Authentication/authorization flaws
- Secrets/credentials in code
- Insecure dependencies
Defining Agents in Plugins
Plugins can define custom agents in their agents/ directory:
my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── agents/ │ ├── security-auditor.md │ ├── performance-analyzer.md │ └── accessibility-checker.md └── skills/ └── ...
Each agent file follows the same YAML frontmatter + markdown body structure.
Using Custom Agents
Via Task Tool
Agent tool with subagent_type="security-auditor" for security analysis.
Via Delegation
/delegate Audit auth module for security issues
The delegation system matches tasks to appropriate custom agents.
Best Practices
- Principle of Least Privilege
Only grant tools the agent actually needs:
Good: Minimal tools for the task
allowed-tools: Read, Grep, Glob
Avoid: Overly permissive
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
- Use Context Forking for Isolation
Good: Isolated exploratory work
context: fork
- Combine Allowed and Disallowed
Explicit whitelist with safety blacklist
allowed-tools: Bash, Read, Grep disallowedTools: Write, Edit
- Clear Agent Descriptions
description: | Security auditor for identifying vulnerabilities in authentication and authorization code. Reports findings without modifying code.
- Model Selection
Use Case Model Model ID
Simple/mechanical tasks haiku claude-haiku-4-5
Development workflows sonnet claude-sonnet-4-6
Deep reasoning/analysis opus claude-opus-4-6
Agent Configuration Fields Reference
Field Type Description
name
string Agent identifier
description
string What the agent does
model
string Model to use (haiku, sonnet, opus)
context
string Context mode: fork or default
permissionMode
string default , acceptEdits , dontAsk , bypassPermissions , or plan
maxTurns
number Maximum agentic turns before agent stops
background
bool Set true to always run as a background task
memory
string Persistent memory scope: user , project , or local
skills
list Skill names to preload into agent context at startup
mcpServers
list MCP server names available to this agent
tools
list Tools the agent can use (in agents/ dir; use allowed-tools in skills)
disallowedTools
list Tools the agent cannot use
created
date Creation date
modified
date Last modification date
reviewed
date Last review date
Common Patterns
Read-Only Research Agent
context: fork allowed-tools: Read, Grep, Glob, WebSearch, WebFetch disallowedTools: Bash, Write, Edit
Safe Code Executor
allowed-tools: Bash, Read disallowedTools: Write, Edit
Documentation Writer
allowed-tools: Read, Write, Edit, Grep, Glob disallowedTools: Bash
Full-Power Developer
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
Agentic Optimizations
Context Configuration
Exploratory research context: fork , model: haiku
Security analysis context: fork , disallowedTools: Bash, Write, Edit
Quick lookups model: haiku , minimal tools
Complex implementation model: sonnet , full tools
Quick Reference
Context Modes
Mode Isolation Use Case
(default) Shared Normal workflows
fork
Isolated Research, experiments
Tool Restriction Patterns
Pattern Fields
Whitelist only allowed-tools: Tool1, Tool2
Blacklist only disallowedTools: Tool1, Tool2
Combined Both fields specified