v1.20Grok Build CLI support →

Subagents

A subagent is a focused agent definition (an AGENT.md with frontmatter) that a parent agent can spawn via Task() without polluting its own context.

When to use a subagent

The parent agent holds the conversation context. Delegating "explore this codebase and return findings" to a subagent keeps the parent's context clean and gives the subagent a tight, well-scoped instruction set. Only Claude and OpenClaw support this pattern (SUBAGENT_CAPABLE_AGENTS). Plugins and workflows can bundle subagent definitions, but the on-disk format is always the same AGENT.md file.

Subagents are not the same as teams. A team runs sibling agents in parallel. A subagent is a child the parent spawns, waits on, and gets a report back from — sequential and hierarchical.

The AGENT.md format

---
name: code-reviewer
description: Reads changed files and surfaces bugs, missing tests, and scope creep.
model: claude-opus-4-7
color: cyan
---

You are a focused code reviewer. Read the diff and every changed file, then
produce a structured review: critical issues (file:line), concerns, verdict.
Do not modify any files. Do not commit. Read only.

The model field controls which model is spawned for this subagent. Omit it to inherit the parent's default. The color field sets the terminal badge color.

Install and manage

agents subagents list                               # table with sync status
agents subagents view code-reviewer                 # model, color, file list
agents subagents add gh:team/subagents --agents claude,openclaw
agents subagents add ~/my-subagents --yes            # local path, skip prompts
agents subagents remove code-reviewer               # delete + unsync

Subagents follow the same layered resolution as every other resource: .agents/subagents/ (project) wins over ~/.agents/subagents/ (user) wins over ~/.agents-system/subagents/ (system). See layers for the full model.

Worked example: read-only reviewer

Install a subagent, then give the parent a task that delegates to it:

agents subagents add ~/Projects/reviewers --yes
agents subagents view code-reviewer

# Now ask the parent to use it:
agents run claude "spawn code-reviewer on the current diff and report back"

Claude reads its .claude/agents/ catalog, sees code-reviewer.md, and spawns it via Task(). The subagent's output arrives as a tool result in the parent's context.

Related