design-sub-agent

Designing Sub-agents

A reasoning skill — no file writes. Think before you build.

Work through every question and checklist item before drafting anything. If any answer is "I'm not sure," resolve it first.

---

When to Build a Sub-agent at All

Build a sub-agent when:

• The task produces verbose output you don't need in the main context (test runs, log processing, research)
• You want to enforce specific tool restrictions or permission modes
• The work is completely self-contained and can return a summary
• The same task type recurs across sessions and benefits from a persistent configuration

Don't build one when:

• The task fits in the current context window without quality loss
• The task needs frequent back-and-forth or iterative refinement with the user
• Multiple phases share significant context — sub-agents start fresh each time
• A skill would work — skills run in the main conversation context and are simpler

Check registry/index.md first. If something covers 80%+ of this task, extend that instead.

Critical constraint: Sub-agents cannot spawn other sub-agents. If a workflow requires nested delegation, chain sub-agents from the main conversation or use skills.

---

Frontmatter Fields — Complete Reference

Sub-agent files use YAML frontmatter for configuration. The markdown body after the frontmatter becomes the system prompt. Only name and description are required.

---
name: my-agent           # Required. Lowercase, hyphens only.
description: ...         # Required. When Claude should delegate here.
tools: Read, Glob, Bash  # Optional. Allowlist — only these tools. Omit to inherit all.
disallowedTools: Write   # Optional. Denylist — removes from inherited set.
model: haiku             # Optional. haiku | sonnet | opus | inherit (default)
permissionMode: auto     # Optional. default | acceptEdits | auto | dontAsk | bypassPermissions | plan
maxTurns: 20             # Optional. Cap on agentic turns before stopping.
memory: project          # Optional. user | project | local — enables persistent memory.
skills:                  # Optional. Preload skill content into context at startup.
  - skill-name
background: true         # Optional. Always run as background task.
mcpServers:              # Optional. MCP servers scoped to this sub-agent only.
  - server-name
isolation: worktree      # Optional. Give sub-agent isolated git worktree copy.
---

System prompt body goes here.