subagent-development

What this skill does

# Subagents Meta Skill

> ## 🚨 MANDATORY: Invoke docs-management First
>
> **STOP - Before providing ANY response about subagents/agents:**
>
> 1. **INVOKE** `docs-management` skill
> 2. **QUERY** for the user's specific topic
> 3. **BASE** all responses EXCLUSIVELY on official documentation loaded
>
> **Skipping this step results in outdated or incorrect information.**
>
> ### Verification Checkpoint
>
> Before responding, verify:
>
> - [ ] Did I invoke docs-management skill?
> - [ ] Did official documentation load?
> - [ ] Is my response based EXCLUSIVELY on official docs?
>
> If ANY checkbox is unchecked, STOP and invoke docs-management first.

## Overview

Central authority for Claude Code subagents (also called sub-agents). This skill uses **100% delegation to docs-management** - it contains NO duplicated official documentation.

**Architecture:** Pure delegation with keyword registry. All official documentation is accessed via docs-management skill queries.

## When to Use This Skill

**Keywords:** subagents, sub-agents, agents, agent file, agent YAML, agent frontmatter, agent tools, agent model, automatic delegation, agent lifecycle, agent resumption, /agents command, programmatic agents, agent SDK, built-in agents, Plan subagent, agent configuration

**Use this skill when:**

- Creating new agent definition files
- Configuring agent tool access
- Selecting agent models (inherit, sonnet, haiku, opus)
- Understanding automatic vs explicit agent invocation
- Working with agent resumption and lifecycle
- Using the /agents CLI command
- Integrating agents with Agent SDK
- Understanding priority resolution (project > CLI > user)
- Working with built-in agents (Plan subagent)
- Troubleshooting agent behavior

## Keyword Registry for docs-management Queries

Use these keywords when querying docs-management skill for official documentation:

### Core Concepts

| Topic | Keywords |
| --- | --- |
| Overview | "subagents", "sub-agents", "agent overview" |
| File Format | "agent file format", "agent YAML frontmatter", "agent file structure" |
| File Locations | "agent file locations", "agent directories", "where to put agents" |

### Configuration

| Topic | Keywords |
| --- | --- |
| YAML Frontmatter | "agent YAML frontmatter", "agent configuration", "agent metadata" |
| Tool Access | "agent tools", "agent tool access", "allowed-tools agents" |
| Model Selection | "agent model selection", "inherit model", "sonnet haiku opus agents" |
| Permission Mode | "permissionMode", "agent permission mode", "acceptEdits", "bypassPermissions" |
| Skills Field | "agent skills field", "skills auto-load", "agent skills configuration" |
| Hooks (v2.1.x) | "agent hooks", "hooks in agent", "agent PreToolUse", "agent PostToolUse" |
| Color (Undocumented) | "agent color", "subagent color", "agent UI color" |

### Behavior

| Topic | Keywords |
| --- | --- |
| Automatic Delegation | "automatic delegation", "agent automatic invocation" |
| Explicit Invocation | "explicit agent invocation", "manual agent call" |
| Lifecycle | "agent lifecycle", "agent execution", "agent completion" |
| Resumption | "agent resumption", "resume agent", "continue agent", "agentId", "resumable agents" |
| Plugin Agents | "plugin agents", "plugin-provided agents", "plugin subagents" |
| Chaining Agents | "chaining subagents", "chain agents", "agent orchestration" |
| Performance | "agent performance", "context efficiency", "agent latency", "parallel agents" |

### CLI and SDK

| Topic | Keywords |
| --- | --- |
| CLI Usage | "/agents command", "agents CLI", "list agents" |
| Agent SDK | "Agent SDK subagents", "programmatic agents", "SDK agent creation" |
| Priority Resolution | "agent priority resolution", "project CLI user agents" |

### Built-in Agents

| Topic | Keywords |
| --- | --- |
| General-purpose | "general-purpose subagent", "general purpose agent", "default subagent" |
| Plan Subagent | "Plan subagent", "planning agent", "implementation planning" |
| Explore Subagent | "Explore subagent", "explore agent", "codebase exploration", "read-only agent" |
| Thoroughness Levels | "thoroughness levels", "quick medium thorough", "exploration depth" |

## Official YAML Frontmatter Reference

**Source:** Query docs-management for `sub-agents.md configuration fields` or `agent YAML frontmatter`

> ⚠️ **STALENESS WARNING:** Do NOT hardcode field names, valid values, or requirements here.
> ALWAYS query docs-management for the authoritative list of YAML frontmatter fields.

### Query Pattern for Official Fields

```text
docs-management: "sub-agents.md configuration fields"
docs-management: "agent YAML frontmatter required optional"
```

### Expected Field Categories

| Category | Query Pattern | What You'll Find |
| --- | --- | --- |
| Required fields | "agent required fields" | Fields that must be present |
| Optional fields | "agent optional fields" | Fields with default behavior |
| Model selection | "agent model selection" | Valid model values |
| Permission modes | "agent permissionMode values" | Valid permission mode values |
| Skills auto-load | "agent skills field" | Skills configuration syntax |

**Important:** The `color` property documented below is NOT in official Claude Code documentation.

## Color Property (Undocumented)

The `color` property is an undocumented feature that sets the UI color for subagents. It is NOT in official Claude Code documentation and may change without notice.

**Available Values:** red, blue, green, yellow, purple, orange, pink, cyan

**Placement:** Typically placed after `model` or at the bottom of YAML frontmatter.

**Example:**

```yaml
---
name: my-agent
description: Description of what this agent does
tools: Read, Grep, Glob
model: haiku
color: blue
---
```

**Warning:** As an undocumented feature, this property:

- May not work in all Claude Code versions
- May be removed or changed without notice
- Should not be relied upon for critical functionality

## Repository Color Standard

This repository uses a semantic color categorization for subagents to provide visual consistency:

### Category Assignments

| Category | Color | Purpose | Agents |
| --- | --- | --- | --- |
| **Documentation/Meta** | purple | Documentation, auditing, meta-skills | docs-researcher, docs-validator, skill-auditor |
| **Code Quality** | blue | Code analysis, review, debugging, testing | code-reviewer, codebase-analyst, debugger, test-generator |
| **Research** | green | Research, information gathering, web content | mcp-research, platform-docs-researcher, web-research |

### Reserved Colors (Future Use)

| Color | Reserved For |
| --- | --- |
| orange | Generation/Creation agents |
| red | Critical/Error handling agents |
| yellow | Warning/Attention agents |
| pink | User-facing/Communication agents |
| cyan | Utility agents |

### When to Assign Colors

When creating new agents for this repository:

1. **Identify the agent's primary purpose** (documentation, code quality, research, etc.)
2. **Match to existing category** if possible
3. **Use reserved colors** only for new categories that match the reserved purpose
4. **Document new categories** if creating a genuinely new type

## Quick Decision Tree

**What do you want to do?**

1. **Create a new agent** -> Query docs-management: "agent file format", "agent YAML frontmatter"
2. **Configure agent tools** -> Query docs-management: "agent tools", "allowed-tools agents"
3. **Select agent model** -> Query docs-management: "agent model selection", "inherit sonnet haiku opus"
4. **Configure permissionMode** -> Query docs-management: "permissionMode", "agent permission mode"
5. **Auto-load skills in agent** -> Query docs-management: "agent skills field", "skills auto-load"
6. **Understand automatic delegation** -> Query docs-management: "automatic delegation agents"
7. **Resume an agent (agentId)** -> Query docs-management: "agent resumption", "agentId", "resumable agents"
8. **Use /agents CLI** -> Query docs-management: "/agents co