Sub Agent Design

Sub-agent Design

This skill provides interpretive guidance for creating Claude Code sub-agents (aka Subagents aka Agents). It helps you understand what the docs mean and how to create excellent sub-agents.

Fundamentals

Everything in this skill is built on top of the box-factory-architecture skill. Load that first!

This skill adds sub-agent-specific guidance on top of that foundation.

Workflow Selection

Quick Start

Sub-agent file structure:

---
name: my-agent
description: Does X when Y. ALWAYS use when Z.
tools: Read, Grep, Glob, Skill
skills: my-plugin:my-design-skill
color: green
---

# My Agent

This sub-agent [purpose].

## Process

1. [Step one]
2. [Step two]

## Constraints

- Never include "ask the user" phrases (sub-agents can't interact with users)

Critical: Sub-agents operate in isolated context and return results. They cannot ask users questions.

Agent Body Structure

The body of a sub-agent (everything after YAML frontmatter) defines its system prompt.

Required:

Optional:

Section naming:

• "Prerequisites" = things that must be true before starting (skill availability, environment)
• "Skill Usage" = navigation pointers for loaded skills (what to consult each for)
• "Constraints" = behavioral limitations during execution
• "Error Handling" = edge case responses (typically a table)

Minimal agent:

# Agent Name

## Process

1. **Step one**
2. **Step two**

Full agent (with skills):

# Agent Name

This sub-agent [purpose].

## Prerequisites

The following skills must be available. If they are not, report failure and stop:

- skill-one
- skill-two

## Skill Usage

Follow the **Workflow Selection** table in each loaded skill to navigate to the right guidance.

**skill-one** - Consult for:

- [Aspect A] (Section Name)
- [Aspect B] (Section Name)

**skill-two** - Consult for:

- [Aspect C] (Section Name)
- [Aspect D] (Section Name)

## Process

1. **Understand requirements** from the caller
2. **Design** by navigating loaded skills:
   - Follow skill-one for [specific decisions]
   - Consult skill-two for [other decisions]
3. **Execute** the task
4. **Validate** - ALL items must pass before completing:
   - [ ] Checklist item one
   - [ ] Checklist item two
   - [ ] Checklist item three
   **If ANY item fails:** Fix before reporting results.
5. **Report results**

## Error Handling

| Situation | Action |
| --- | --- |
| Required skills not loaded | Report failure, do not attempt task |
| Unclear requirements | Make reasonable assumptions, document them |

Why this structure works:

• Skill Usage tells the agent WHERE to look (navigation pointers, not duplicated content)
• Process step 2 references specific skills for specific decisions
• Process step 4 inlines the checklist so it can't be skipped

The skills Field (Best Practice)

The skills YAML field auto-loads skills when the sub-agent starts. This is especially valuable for Box Factory sub-agents that need design skills.

---
name: agent-writer
description: Creates sub-agents. ALWAYS use when creating sub-agents.
tools: Read, Write, Edit, Glob, Grep, Skill, WebFetch
skills: box-factory:sub-agent-design
---

When to use:

Box Factory pattern: Writer sub-agents should declare their design skill dependency:

• agent-writer → skills: box-factory:sub-agent-design
• skill-writer → skills: box-factory:skill-design
• command-writer → skills: box-factory:slash-command-design

Note: Still include Skill in your tools list - the sub-agent may need to load additional skills during execution.

Example of conditional skill loading (Skill tool in body pattern):

---
name: component-validator
description: Validates Claude Code components. MUST BE USED when validating plugins or components.
tools: Read, Grep, Glob, Skill, WebFetch
---

# Component Validator

## Process

1. **Identify component type** from file structure
2. **Load relevant design skill:**
   - Plugin → `Skill box-factory:plugin-design`
   - Sub-agent → `Skill box-factory:sub-agent-design`
   - Skill → `Skill box-factory:skill-design`
   - Command → `Skill box-factory:slash-command-design`
3. **Validate** against loaded skill's patterns

This sub-agent can't declare a single skill upfront because which skill it needs depends on what component type it discovers at runtime.

Skill Usage Section Pattern

When an agent loads skills via the skills field, include a Skill Usage section. This teaches the agent HOW to traverse the loaded skills, not just THAT they're loaded.

Problem it solves: Skills auto-load content, but the agent might not know which parts to consult for which decisions. Generic instructions like "use the skill" don't guide navigation.

Structure:

## Skill Usage

Follow the **Workflow Selection** table in each loaded skill to navigate to the right guidance.

**skill-name** - Consult for:

- [What to look up] (Section Name in skill)
- [Another aspect] (Another Section)

Key principles:

Critical prohibition: When an agent references a skill it loads, use indirect references (section names, concept names) NOT the skill's internal file paths. A skill's internal file structure is an implementation detail from the agent's perspective.

• ✅ (Quick Start) - section name in skill
• ✅ (Tool Selection Philosophy) - section name in skill
• ✅ (the skill's guidance on X) - indirect reference
• ❌ (gotchas.md) - skill's internal file (agent shouldn't know this)
• ❌ (skill-structure.md) - skill's internal file

Example (concrete):

## Skill Usage

Follow the **Workflow Selection** table in each loaded skill.

**box-factory-architecture** - Consult for:

- Component paths (where to put files)
- Isolation model (why agents can't ask questions)
- Communication patterns (CAN/CANNOT matrix)

**sub-agent-design** - Consult for:

- YAML frontmatter structure (Quick Start)
- Tool selection (Tool Selection Philosophy)
- Color selection (Color Selection)

When to skip: If agent loads no skills or loads them conditionally via Skill tool (runtime decision), Skill Usage section is not needed.

Inlining Quality Checklists

For critical validation, inline the checklist in the Process section. Don't just reference a skill's checklist—agents may skip the reference.

Problem it solves: "Validate against the skill's checklist" is easy to skip or satisfy superficially. Inlined checklists force explicit verification.

Pattern:

4. **Validate** - ALL items must pass before completing:

   - [ ] Item one
   - [ ] Item two
   - [ ] Item three

   **If ANY item fails:** Fix before reporting results.

What to inline:

Balance: Inline only the checklist items themselves (1-2 lines each). Keep explanations and rationale in the skill. This maintains single source of truth while ensuring validation happens.

Example (from sub-agent creation):

7. **Validate** - ALL items must pass before completing:

   - [ ] Fetched official docs (or noted why skipped)
   - [ ] Valid YAML frontmatter with required fields
   - [ ] No forbidden language ("ask the user", "confirm with")
   - [ ] Tools match autonomous responsibilities
   - [ ] Description has specific triggering conditions
   - [ ] Color set with semantic meaning

   **If ANY item fails:** Fix before reporting results.

Official Documentation

Claude Code changes rapidly and is post-training knowledge. Fetch these docs when creating sub-agents to ensure current syntax:

• https://code.claude.com/docs/en/sub-agents.md - Core specification and examples
• https://code.claude.com/docs/en/settings#tools-available-to-claude - Verify tool names
• https://code.claude.com/docs/en/model-config.md - Current model options

Sub-agent-Skill Relationship

Core principle: When a sub-agent loads a skill, knowledge lives in the skill; the sub-agent focuses on process.

Decision logic:

Why this matters:

• Avoids duplication (same knowledge in sub-agent AND skill)
• Single source of truth (update skill, all sub-agents benefit)
• Smaller sub-agent prompts (less context consumed)
• Skills are reusable across multiple sub-agents

Pattern for skill-backed sub-agents:

Prefer the skills YAML field (see The skills Field) to auto-load skills at startup. The sub-agent body then focuses on process, with a Skill Usage section providing navigation:

## Skill Usage

Follow the **Workflow Selection** table in each loaded skill.

**my-skill** - Consult for:

- [Aspect A] (Section Name)
- [Aspect B] (Section Name)

## Process

1. **Design** by navigating loaded skills:
   - Consult my-skill for [specific decisions]
2. **Execute task**
3. **Validate** - ALL items must pass:
   - [ ] Checklist item from skill
   - [ ] Another item
   **If ANY fails:** Fix before reporting.

See Skill Usage Section Pattern and Inlining Quality Checklists for detailed guidance.

Pattern for standalone sub-agents (no skill):

## Process

1. **Understand requirements** [process step]

2. **Apply domain knowledge** [embedded in sub-agent]:
   - Guideline one
   - Guideline two
   - Decision framework here

3. **Execute task** [process step]

Anti-pattern: Sub-agent loads skill but also embeds same knowledge inline. This causes:

• Maintenance burden (update two places)
• Context waste (duplicate content loaded)
• Potential conflicts (sub-agent and skill disagree)

Tool Selection Philosophy

General principle: Match tools to the sub-agent's job. Reviewers should be read-only; builders need write access.

Never Include AskUserQuestion

Sub-agents operate in isolation and cannot interact with users. The AskUserQuestion tool will fail silently or cause unexpected behavior. If your sub-agent needs clarification, it must infer from context or make reasonable assumptions.

Bash is Foundational for Creators

Any sub-agent with creative responsibilities needs Bash, regardless of output type. Even a sub-agent that only produces markdown files needs shell operations:

Rule of thumb: If a sub-agent creates files, include Bash. The Write tool handles file content; Bash handles the filesystem orchestration around it.

WebFetch Pairs with Skills for Verification

When a sub-agent loads skills via the skills field (especially for specifications or rapidly-changing domains), also include WebFetch:

tools: Read, Write, Edit, Glob, Grep, Skill, WebFetch
skills: box-factory:sub-agent-design

Why: Skills encode knowledge delta (interpretive guidance beyond docs), but the underlying specifications change. Sub-agents should verify current official docs against skill guidance when uncertain.

Pattern: The sub-agent's process should include a step like:

"If uncertain about current spec, fetch official documentation to verify"

This maintains the low-maintenance-first philosophy—skills provide stable interpretive guidance while WebFetch catches spec drift.

Color Selection

The color field sets visual distinction for sub-agents in the status line.

• Official spec: Optional
• Box Factory requirement: Required for all sub-agents

Note: Color support is not documented officially. The following was verified through testing—Claude often guesses wrong colors that don't render.

Supported colors (7 total): red, green, blue, yellow, cyan, purple, orange

Not supported: magenta, white, black, gray, grey, *Bright variants

Semantic mapping:

Example:

---
name: code-reviewer
color: green
---

Guidelines:

• Match color to primary function, not secondary features
• Be consistent within a plugin (all quality sub-agents green)
• Reserve orange for sub-agents that don't fit established categories

Description Field Design

The description field determines when Main Claude delegates to your sub-agent. This is critical for autonomous invocation.

Official requirement: "Natural language explanation of when to invoke the subagent"

Quality test: Would Main Claude invoke this sub-agent based on context alone, or only when explicitly asked?

Guidelines:

• State WHEN to use (triggering conditions), not just WHAT it does
• Be specific about context and use cases
• Test empirically - if your sub-agent isn't being invoked automatically, revise the description
• Avoid overly generic descriptions that match too many scenarios

Quality Checklist

Before finalizing a sub-agent:

1. Fetch official docs - Verify against current specification
2. Check structure - Valid YAML frontmatter, required fields present
3. Scan for forbidden language - No user interaction phrases
4. Validate tools - Match autonomous responsibilities, no AskUserQuestion
5. Test description - Specific triggering conditions, not generic
6. Review system prompt - Single H1, clear structure, actionable instructions
7. Verify no hardcoding - No version-specific details that will become outdated
8. Set color - Choose semantic color matching sub-agent's primary function (creator=blue, quality=green, ops=yellow, meta=purple, research=cyan, safety=red, other=orange)
9. If agent loads skills via skills field:
   • Skill Usage section present with navigation pointers
   • Navigation pointers use indirect references (section names), NOT skill's internal file paths
   • Process steps reference specific skill sections
   • Quality checklist inlined in validation step (not just referenced)