Agent Configuration#
Agent configuration in Claude Code uses Markdown files with YAML frontmatter to define autonomous subprocesses that handle complex, multi-step tasks. Each agent file lives under an agents/ subdirectory within a plugin (e.g., plugins/my-plugin/agents/agent-name.md) and is auto-discovered at session start .
The Agent Teams feature — which enables a parent Claude instance to spawn and coordinate these agents at runtime — shipped in v2.1.32 as a research preview behind the env flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 .
Frontmatter Schema#
The agent-development SKILL.md documents the complete file format. Fields at a glance:
| Field | Required | Values | Notes |
|---|---|---|---|
name | Yes | lowercase, hyphens, 3–50 chars | Must start/end with alphanumeric |
description | Yes | Text + <example> blocks | Primary dispatch signal — Claude reads this to decide when to invoke the agent |
model | Yes | inherit / sonnet / opus / haiku | Use inherit unless the agent needs a specific capability tier |
color | Yes | blue cyan green yellow magenta red | Visual identifier in the UI |
tools | No | Array of tool names | Omit for full access; use least-privilege otherwise |
memory | No | user / project / local | Persistent memory scope; added in v2.1.33 |
isolation | No | "worktree" | Runs the agent in an isolated git worktree |
A real example — the agent-creator agent in the plugin-dev plugin — shows model: sonnet, color: magenta, and tools: ["Write", "Read"] .
Subagent Spawning Restrictions#
A parent agent can restrict which child agent types it is allowed to spawn using Task(agent_type) syntax inside the tools frontmatter (added v2.1.33):
tools: ["Read", "Write", "Task(code-reviewer)", "Task(test-generator)"]
This declares the parent is permitted to dispatch only the listed agent types . A later fix in v2.1.147 resolved a bug where declaring multiple Agent(...) types caused all but the last to be silently dropped .
Lifecycle Hooks for Multi-Agent Monitoring#
v2.1.33 introduced two hook events specifically for monitoring teammate agents :
| Hook Event | Fires when… |
|---|---|
TeammateIdle | A teammate agent becomes idle |
TaskCompleted | A teammate finishes its assigned task |
Both hooks support the {"continue": false, "stopReason": "..."} response to halt a teammate — identical to the behavior of the Stop hook .
Hook configuration uses the same hooks/hooks.json format as other hook types. For plugin hooks, events are wrapped in {"hooks": {...}}; for user settings in .claude/settings.json, events sit at the top level . See the hook-development SKILL.md for full hook output formats, matchers, and timeout defaults.
Observability#
Parent–child relationships are tracked via OTEL spans: agent_id and parent_agent_id attributes appear on claude_code.tool spans, and background subagent spans nest under the dispatching Agent tool span. All sub-agent API requests carry x-claude-code-agent-id / x-claude-code-parent-agent-id HTTP headers .
The env variable CLAUDE_CODE_SUBAGENT_MODEL controls the model used by teammate processes; a fix resolved this variable not applying to agent-teams spawned teammates .
Key Source Files#
| Path | What it covers |
|---|---|
plugins/plugin-dev/skills/agent-development/SKILL.md | Full frontmatter schema, system-prompt guidelines, validation rules |
plugins/plugin-dev/agents/agent-creator.md | Live example of a real agent with tools/model/color frontmatter |
plugins/plugin-dev/skills/hook-development/SKILL.md | Hook types, output formats, matchers, TeammateIdle/TaskCompleted usage |
CHANGELOG.md | v2.1.32–v2.1.33 feature introductions; subsequent bug fixes |
