/writing-subagents

name: writing-subagents
description: Creates specialized Claude Code subagents in .claude/agents/ with minimal tools, clear triggers, and isolated context. Use when user says 'create agent', 'add reviewer', 'specialized agent', 'isolated context task'.

Writing Subagents

Overview

**Writing subagents IS creating specialized workers with isolated contexts.**

Subagents run via the Agent tool with their own context window, tools, and system prompt. Use for tasks that benefit from focused expertise.

**Core principle:** One agent, one responsibility. Bloated agents become unfocused.

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 0. Fetch latest official subagent spec 1. Analyze requirements 2. Document problem context 3. Design agent configuration 4. Validate structure 5. Test invocation 6. Verify behavior 7. REFACTOR - quality review

Announce: "Created 8 tasks (0–7). Starting execution..."

Agent Configuration Process

| Phase | Focus | What You Do | |-------|-------|-------------| | **Requirements** | Understanding | Identify what specialized task needs isolation | | **Analysis** | Problem definition | Document why main agent isn't sufficient | | **Design** | Configuration | Plan agent tools, model, and system prompt | | **Implementation** | Creation | Write agent file with proper configuration | | **Optimization** | Refinement | Fine-tune tools and prompts for efficiency |

Task 0: Fetch Latest Official Spec

**Goal:** Pull the current Anthropic subagent spec before designing — never trust cached memory.

**Action:**

Skill tool: fetching-claude-docs
  component: subagent
  question: "frontmatter fields, tool inheritance, model selection,
             description trigger format (PROACTIVELY, examples), context isolation"

**Verification:** Received YAML with `source: https://code.claude.com/docs/en/sub-agents.md` and non-empty `spec_excerpt`. Use this as the **authoritative reference** for Tasks 1–7; if any rule in this SKILL conflicts with the fetched spec, the fetched spec wins (and flag the conflict for refactoring).

Task 1: Analyze Requirements

**Goal:** Understand what specialized task needs isolation.

**Questions to answer:**

• What specific task needs a subagent?
• Why can't the main agent do this?
• What tools does this agent need?
• Should it be proactive or manual?

**When to use subagents:**

• Task needs isolated context (code review, deep analysis)
• Task would pollute main conversation
• Task is repetitive and well-defined
• Task benefits from specialized system prompt

See [references/examples.md](references/examples.md) for subagent templates and trigger examples.

**Built-in subagent types (consider BEFORE creating custom agents):**

| Type | Model | Tools | Use Case | |------|-------|-------|----------| | `Explore` | Haiku | Read-only (no Write/Edit) | Fast codebase search, analysis | | `Plan` | Inherit | Read-only | Research and planning | | `general-purpose` | Inherit | All | Complex multi-step tasks |

**Decision:** Can a built-in type handle this? If yes, use it directly via the Agent tool — no agent file needed.

**Verification:** Can describe the agent's single responsibility in one sentence.

Task 2: Document Problem Context

**Goal:** Clearly understand why the main agent is insufficient for this task.

**Analysis points:** 1. What specific challenges arise when using the main agent? 2. How would task isolation improve the outcome? 3. What context pollution or focus issues occur? 4. What specialized expertise would help?

**Verification:** Documented specific problems that justify creating a specialized subagent.

Task 3: Design Agent Configuration

**Goal:** Plan the agent configuration to address the documented problems.

**Before drafting the system prompt, walk through [prompt-design-principles.md](../../references/prompt-design-principles.md):**

• 5-skeleton framework — the system prompt needs Role (agent's job, not persona), Scope (what this agent does and doesn't handle), Workflow (procedure for its task), Standards (output rules), Completion (what "done" means for this agent's output).
• Failure-mode reverse engineering — anticipate what this agent could get wrong and write rules against those specific failures.
• Conditional dispatch — if the agent handles multiple task variants, write per-variant behavior, not absolute rules.
• Creative-constraint balance — decide what axes the agent can vary on (e.g., review phrasing) vs. must stay fixed (e.g., output YAML structure).

Agent Location

.claude/agents/      # Project-level
~/.claude/agents/    # User-level (global)

Agent Format

---
name: agent-name
description: What this agent does. Use proactively when [triggers].
tools: Read, Grep, Glob, Bash
model: sonnet
---

System prompt for the agent.

## Role
[Clear description of the agent's responsibility]

## Process
[Steps the agent should follow]

## Output Format
[Expected output structure]

Configuration & Tools

See [references/agent-spec.md](references/agent-spec.md) for full configuration fields, model selection, context:fork guidelines, and tool permissions.

**Key rules:**

• `name`: lowercase with hyphens, matches filename
• `description`: include 2-4 concrete examples in `<example>` blocks showing triggering conditions
• `model`: specified explicitly; `inherit` is an anti-pattern in plugin agents (only project/user-level agents in `.claude/agents/` may omit)
• `color`: unique color per agent (blue, green, red, purple, yellow)
• `tools`: minimal set (principle of least privilege). Subagents cannot request permissions at runtime.
• Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode`
• System prompt should encourage parallel tool calls for independent operations (e.g. "When reading N files, fire N Read calls in a single response")

| Agent Type | Recommended Tools | |------------