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, 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
effort: low
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 (tools vs disallowedTools)

Field	Purpose	Behavior
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. allowed-tools is the skill spelling of the whitelist: on an agent Claude Code ignores it without an error, so the agent keeps every tool. 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

1. Principle of least privilege — grant only the tools the agent needs.

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

3. Combine tools + disallowedTools — explicit whitelist with a safety blacklist.

4. Clear descriptions — describe what the agent does and its boundaries.

5. Model and effort — pick the model by task shape. opus is the default for judgement work (review, debugging, multi-file edits, untrusted input). fable is for the hardest delegated reasoning. sonnet with an explicit effort: fits bounded work whose done check fits in one sentence and whose wrong answer is cheap to catch. haiku fits a lean read-only reader whose output a stronger stage checks. An agent's output re-enters the main loop, so a weaker model's output needs that check; escalate a miss to opus rather than retrying on the same model. scripts/check-agent-model.sh enforces the shape for plugin agents. See .claude/rules/agent-development.md § "Model Selection for Agents".

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.

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