Custom Agent Definitions Skill

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
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization flaws
4. Secrets/credentials in code
5. 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

1. 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

2. Use Context Forking for Isolation

# Good: Isolated exploratory work
context: fork

3. Combine Allowed and Disallowed

# Explicit whitelist with safety blacklist
allowed-tools: Bash, Read, Grep
disallowedTools: Write, Edit

4. Clear Agent Descriptions

description: |
  Security auditor for identifying vulnerabilities in authentication
  and authorization code. Reports findings without modifying code.

5. 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 |

Agent Skills: Custom Agent Definitions

Install this agent skill to your local

Skill Files