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
| Use this skill when... |
Use agent-teams instead when... |
Authoring a new .md agent definition file in .claude/agents/ |
Spawning multiple already-defined agents that coordinate as a team |
Configuring a single agent's model, allowed-tools, or context: fork |
Setting up a lead/teammate architecture with a shared task list |
| Constraining tool access for a specialised read-only or write-restricted agent |
Sequencing parallel work across worktrees (see parallel-agent-dispatch) |
| Writing the system prompt that defines what one agent does |
Auditing existing agent definitions for security (see meta-audit) |
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
| Value |
Behavior |
fork |
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 |
Use fork for exploratory research, parallel investigations, and isolated
experiments. See REFERENCE.md → Isolated research agent.
Tool Access (allowed vs disallowed)
| 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 |
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
| Field |
Type |
Description |
name |
string |
Agent identifier |
description |
string |
What the agent does |
model |
string |
opus, sonnet, haiku, fable, inherit, or a full model ID |
effort |
string |
low, medium, high, xhigh, max — overrides the session effort while this agent runs; default inherits. The cost lever for mechanical delegates |
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 / modified / reviewed |
date |
Lifecycle dates |
Best Practices
Principle of least privilege — grant only the tools the agent needs.
Use context: fork for isolation — exploratory work shouldn't pollute main context.
Combine allowed + disallowed — explicit whitelist with a safety blacklist.
Clear descriptions — describe what the agent does and its boundaries.
Model and effort — model: opus is the floor for any agent whose output
re-enters the main loop (a weaker delegate degrades everything downstream;
scripts/check-agent-model.sh enforces it for plugin agents). fable is
sanctioned for the hardest delegated reasoning. Tune cost with effort:
(low for mechanical work), not by downgrading the model. The one
exception is the cold-read-gate haiku reader, which is a measurement
instrument, not a delegate. See .claude/rules/agent-development.md §
"Model Selection for Agents" (repo) and
~/.claude/rules/agent-and-tool-selection.md (user-global).
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.
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.
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 |
Related
- REFERENCE.md — full worked YAML examples and snippets
agent-teams — multi-agent coordination via the implicit teamparallel-agent-dispatch — worktree preflight, scope budgets, loud-failure contractmeta-audit — auditing existing agent definitions for security/completeness.claude/rules/agent-development.md — agent lifecycle and field semantics
1---2name: custom-agent-definitions3description: Write and configure custom agent definitions in Claude Code agents/ directory. Use when creating an agent .md file, defining a specialized agent, or configuring agent tools.4---5
6# Custom Agent Definitions
7
8Expert knowledge for defining and configuring custom agents in Claude Code.
9
10For full worked YAML examples (isolated research agent, read-only explorer,
11complete security auditor, plugin layout, common patterns), see
12[REFERENCE.md](REFERENCE.md).
13
14## When to Use This Skill
15
16| Use this skill when... | Use agent-teams instead when... |
17|---|---|
18| Authoring a new `.md` agent definition file in `.claude/agents/` | Spawning multiple already-defined agents that coordinate as a team |
19| Configuring a single agent's `model`, `allowed-tools`, or `context: fork` | Setting up a lead/teammate architecture with a shared task list |
20| Constraining tool access for a specialised read-only or write-restricted agent | Sequencing parallel work across worktrees (see parallel-agent-dispatch) |
21| Writing the system prompt that defines what one agent does | Auditing existing agent definitions for security (see meta-audit) |
22
23## Core Concepts
24
25**Custom agents** let you define specialized agent types beyond the built-in
26ones (Explore, Plan, Bash, etc.). Each can have its own model, tools, and
27context configuration. They are defined in `.claude/agents/` or via plugin
28`agents/` directories, with YAML frontmatter + a markdown system prompt:
29
30```yaml
31---
32name: my-custom-agent
33description: What this agent does
34model: sonnet
35allowed-tools: Bash, Read, Grep, Glob
36---
37
38# Agent System Prompt
39
40Instructions and context for the agent...
41```
42
43## Key Fields
44
45### Context Forking
46
47| Value | Behavior |
48|-------|----------|
49| `fork` | Independent context copy — agent sees parent history but changes don't affect parent |
50| (default) | Agent shares context with parent and can see/modify conversation state |
51
52Use `fork` for exploratory research, parallel investigations, and isolated
53experiments. See [REFERENCE.md → Isolated research agent](REFERENCE.md#isolated-research-agent-context-fork).
54
55### Tool Access (allowed vs disallowed)
56
57| Field | Purpose | Behavior |
58|-------|---------|----------|
59| `allowed-tools` | Whitelist of permitted tools | Agent can ONLY use these tools |
60| `disallowedTools` | Blacklist of forbidden tools | Agent can use all tools EXCEPT these |
61
62Use `disallowedTools` for read-only agents, restricting dangerous capabilities,
63and sandboxing. The two combine — an explicit whitelist plus a safety blacklist.
64See [REFERENCE.md → Read-only explorer](REFERENCE.md#read-only-explorer-disallowedtools).
65
66### Agent Field for Delegation
67
68The `agent` field specifies which agent type to use when delegating via the Agent
69tool, letting commands and skills name a preferred agent type:
70
71```yaml
72agent: security-auditor
73```
74
75## Agent Configuration Fields Reference
76
77| Field | Type | Description |
78|-------|------|-------------|
79| `name` | string | Agent identifier |
80| `description` | string | What the agent does |
81| `model` | string | `opus`, `sonnet`, `haiku`, `fable`, `inherit`, or a full model ID |
82| `effort` | string | `low`, `medium`, `high`, `xhigh`, `max` — overrides the session effort while this agent runs; default inherits. The cost lever for mechanical delegates |
83| `context` | string | Context mode: `fork` or default |
84| `permissionMode` | string | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |
85| `maxTurns` | number | Maximum agentic turns before agent stops |
86| `background` | bool | Set `true` to always run as a background task |
87| `memory` | string | Persistent memory scope: `user`, `project`, or `local` |
88| `skills` | list | Skill names to preload into agent context at startup |
89| `mcpServers` | list | MCP server names available to this agent |
90| `tools` | list | Tools the agent can use (in agents/ dir; use `allowed-tools` in skills) |
91| `disallowedTools` | list | Tools the agent cannot use |
92| `created` / `modified` / `reviewed` | date | Lifecycle dates |
93
94## Best Practices
95
961. **Principle of least privilege** — grant only the tools the agent needs.
972. **Use `context: fork` for isolation** — exploratory work shouldn't pollute main context.
983. **Combine allowed + disallowed** — explicit whitelist with a safety blacklist.
994. **Clear descriptions** — describe what the agent does and its boundaries.
1005. **Model and effort** — `model: opus` is the floor for any agent whose output
101 re-enters the main loop (a weaker delegate degrades everything downstream;
102 `scripts/check-agent-model.sh` enforces it for plugin agents). `fable` is
103 sanctioned for the hardest delegated reasoning. Tune cost with `effort:`
104 (`low` for mechanical work), not by downgrading the model. The one
105 exception is the `cold-read-gate` haiku reader, which is a measurement
106 instrument, not a delegate. See `.claude/rules/agent-development.md` §
107 "Model Selection for Agents" (repo) and
108 `~/.claude/rules/agent-and-tool-selection.md` (user-global).
1096. **Report failures loudly** — a dispatched agent that hits a wall must say so
110 in its final message, never a one-word summary like `Terminal.` / `Done.` /
111 `Stopped.` On a blocker it should commit and push its in-progress work, open a
112 draft PR, and state exactly what stopped it and which tools were denied. A
113 one-word surrender is indistinguishable from success to the orchestrator, so
114 the work is silently cleaned up and lost (issue
115 [#1422](https://github.com/laurigates/claude-plugins/issues/1422)). See
116 `parallel-agent-dispatch` → "Loud-failure contract" for the dispatch-prompt
117 form every brief should carry.
118
1197. **Prefer a Skill-less agentType for read-only fan-out** — an agent that
120 only reads files and emits structured output should NOT carry the `Skill`
121 tool. Every `Skill`-bearing agent pays a ~25k-token `skill_listing` +
122 `deferred_tools_delta` context tax before its first tool call, which can push
123 read-heavy fan-out subagents over their context window. Use a lean read-only
124 agent (e.g. `agents-plugin:review`) instead. See
125 `parallel-agent-dispatch` → "Skill-less agentType for Read-Only Fan-Out"
126 (issues
127 [#1549](https://github.com/laurigates/claude-plugins/issues/1549) /
128 [#1550](https://github.com/laurigates/claude-plugins/issues/1550)).
129
130Worked YAML for each practice is in [REFERENCE.md → Best-practice snippets](REFERENCE.md#best-practice-snippets).
131
132## Quick Reference
133
134### Context Modes
135
136| Mode | Isolation | Use Case |
137|------|-----------|----------|
138| (default) | Shared | Normal workflows |
139| `fork` | Isolated | Research, experiments |
140
141### Tool Restriction Patterns
142
143| Pattern | Fields |
144|---------|--------|
145| Whitelist only | `allowed-tools: Tool1, Tool2` |
146| Blacklist only | `disallowedTools: Tool1, Tool2` |
147| Combined | Both fields specified |
148
149## Related
150
151- [REFERENCE.md](REFERENCE.md) — full worked YAML examples and snippets
152- `agent-teams` — multi-agent coordination via the implicit team
153- `parallel-agent-dispatch` — worktree preflight, scope budgets, loud-failure contract
154- `meta-audit` — auditing existing agent definitions for security/completeness
155- `.claude/rules/agent-development.md` — agent lifecycle and field semantics
laurigates