Custom Agent Definitions

Custom Agent Definitions

Expert knowledge for defining and configuring custom agents in Claude Code.

For full worked YAML examples (isolated research agent, read-only explorer, complete security auditor, plugin layout, common patterns), see REFERENCE.md.

When to Use This Skill

Core Concepts

Custom agents let you define specialized agent types beyond the built-in ones (Explore, Plan, Bash, etc.). Each can have its own model, tools, and context configuration. They are defined in .claude/agents/ or via plugin agents/ directories, with YAML frontmatter + a markdown system prompt:

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

Key Fields

Context Forking

Use fork for exploratory research, parallel investigations, and isolated experiments. See REFERENCE.md → Isolated research agent.

Tool Access (allowed vs disallowed)

Use disallowedTools for read-only agents, restricting dangerous capabilities, and sandboxing. The two combine — an explicit whitelist plus a safety blacklist. See REFERENCE.md → Read-only explorer.

Agent Field for Delegation

The agent field specifies which agent type to use when delegating via the Agent tool, letting commands and skills name a preferred agent type:

agent: security-auditor

Agent Configuration Fields Reference

Best Practices

1. Principle of least privilege — grant only the tools the agent needs. 2. Use `context: fork` for isolation — exploratory work shouldn't pollute main context. 3. Combine allowed + disallowed — explicit whitelist with a safety blacklist. 4. Clear descriptions — describe what the agent does and its boundaries. 5. Model selection — sonnet for development workflows, opus for deep reasoning/analysis. (See .claude/rules/agent-and-tool-selection.md for the repo's Opus-for-subagents guidance.) 6. Report failures loudly — a dispatched agent that hits a wall must say so in its final message, never a one-word summary like Terminal. / Done. / Stopped. On a blocker it should commit and push its in-progress work, open a draft PR, and state exactly what stopped it and which tools were denied. A one-word surrender is indistinguishable from success to the orchestrator, so the work is silently cleaned up and lost (issue #1422). See parallel-agent-dispatch → "Loud-failure contract" for the dispatch-prompt form every brief should carry.

7. Prefer a Skill-less agentType for read-only fan-out — an agent that only reads files and emits structured output should NOT carry the Skill tool. Every Skill-bearing agent pays a ~25k-token skill_listing + deferred_tools_delta context tax before its first tool call, which can push read-heavy fan-out subagents over their context window. Use a lean read-only agent (e.g. agents-plugin:review) instead. See parallel-agent-dispatch → "Skill-less agentType for Read-Only Fan-Out" (issues #1549 / #1550).

Worked YAML for each practice is in REFERENCE.md → Best-practice snippets.

Agentic Optimizations

Quick Reference

Context Modes

Tool Restriction Patterns

Related

• REFERENCE.md — full worked YAML examples and snippets
• agent-teams — multi-agent coordination via the implicit team
• parallel-agent-dispatch — worktree preflight, scope budgets, loud-failure contract
• meta-audit — auditing existing agent definitions for security/completeness
• .claude/rules/agent-development.md — agent lifecycle and field semantics

Custom Agent Definitions — Reference

Supporting material for `custom-agent-definitions`. Loaded on demand. The decision tables, schema overview, field reference, and best practices live in SKILL.md; this file carries the full worked YAML examples and configuration snippets.

Isolated research agent (context: fork)

---
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 conflicting approaches, isolated experiments, background tasks that run independently.

Read-only explorer (disallowedTools)

---
name: read-only-explorer
description: Explore codebase without modifications
model: sonnet
allowed-tools: Bash, Read, Grep, Glob
disallowedTools: Write, Edit, NotebookEdit
---

# Read-Only Explorer

Explore and analyze code. Do not make any modifications.

When to use `disallowedTools`: read-only agents that explore but don't modify, restricting dangerous capabilities (Bash execution), sandboxing agents for specific tasks, security-sensitive contexts.

Complete example: security auditor

---
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 define custom agents in their agents/ directory; each file follows the same YAML frontmatter + markdown body structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── security-auditor.md
│   ├── performance-analyzer.md
│   └── accessibility-checker.md
└── skills/
    └── ...

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.

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

Best-practice snippets

Principle of least privilege — grant only the tools the agent 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

Combine an explicit whitelist with a safety blacklist:

allowed-tools: Bash, Read, Grep
disallowedTools: Write, Edit

Clear, multi-line description:

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