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 `isolation`	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 isolation settings. 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: isolated by default

A named agent always starts in a fresh context: its own system prompt, the brief the caller writes, CLAUDE.md, and any preloaded skills:. It does not see the caller's conversation history, and no agent frontmatter field changes that.

Want	Use
A delegate that keeps verbose work out of the main context	A named agent — isolation is the default, no field needed
A subagent that already knows the conversation so far	`subagent_type: "fork"` on the `Agent` call (fork mode is off under `-p` unless `CLAUDE_CODE_FORK_SUBAGENT=1`)

context: fork is a skill frontmatter field that runs a skill body in a new subagent. On an agent it is not a documented field, and Claude Code ignores it without an error. See REFERENCE.md → Isolated research agent and .claude/rules/agent-development.md § Context Isolation.

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
`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.
Rely on default isolation — a named agent never sees the caller's conversation, so exploratory work stays out of the main context without any field. Only documented agent fields take effect; an unrecognized key, such as a skill's context:, is ignored without an error.
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 Inheritance

Dispatch	Sees the caller's conversation	Use Case
Named agent (`subagent_type: "<name>"`)	No — brief only	Research, review, tool-bounded work
`subagent_type: "fork"`	Yes — the whole conversation	Side task that needs the prior context

Tool Restriction Patterns

Pattern	Fields
Whitelist only	`allowed-tools: Tool1, Tool2`
Blacklist only	`disallowedTools: Tool1, Tool2`
Combined	Both fields specified

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