Central authority for Claude Code subagents (sub-agents). Covers agent file format, YAML frontmatter, tool access configuration, model selection (inherit, sonnet, haiku, opus), automatic delegation, agent lifecycle, resumption, command-line usage (/agents), Agent SDK programmatic agents, priority resolution, and built-in agents (Plan subagent). Assists with creating agents, configuring agent tools, understanding agent behavior, and troubleshooting agent issues. Delegates 100% to docs-management skill for official documentation.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
references/undocumented-features.mdreferences/validation-checklist.md🚨 MANDATORY: Invoke docs-management First
STOP - Before providing ANY response about subagents/agents:
- INVOKE
docs-managementskill- QUERY for the user's specific topic
- 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.
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.
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:
Use these keywords when querying docs-management skill for official documentation:
| 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" |
| 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" |
| Color (Undocumented) | "agent color", "subagent color", "agent UI color" |
| 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" |
| 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" |
| 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" |
Source: doc_id: code-claude-com-docs-en-sub-agents section #configuration-fields
These are the officially documented YAML frontmatter fields for subagent definition files:
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier using lowercase letters and hyphens |
description | Yes | Natural language description of the subagent's purpose |
tools | No | Comma-separated list of specific tools. If omitted, inherits all tools from main thread |
model | No | Model alias (sonnet, opus, haiku) or 'inherit' to use main conversation's model |
permissionMode | No | Valid values: default, acceptEdits, bypassPermissions, plan, ignore |
skills | No | Comma-separated list of skill names to auto-load when subagent starts |
Important: The color property documented below is NOT in official Claude Code documentation.
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:
---
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:
This repository uses a semantic color categorization for subagents to provide visual consistency:
| 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 |
| 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 creating new agents for this repository:
What do you want to do?
These scenarios should activate this skill:
| Skill | Relationship |
|---|---|
| docs-management | Primary delegation target (100%) - all official documentation |
| agent-sdk-development | Agent SDK-specific guidance for programmatic agents |
| skill-development | Skills can be auto-loaded by agents via skills field |
| current-date | For audit timestamps and verification dates |
User asks: "How do I create an agent?"
1. Invoke docs-management skill
2. Use keywords: "agent file format", "agent YAML frontmatter"
3. Load official documentation
4. Provide guidance based EXCLUSIVELY on official docs
User asks: "I want to create an agent with restricted tools that uses Haiku"
1. Invoke docs-management skill with multiple queries:
- "agent file format", "agent YAML frontmatter"
- "agent tools", "allowed-tools agents"
- "agent model selection", "haiku agents"
2. Synthesize guidance from official documentation
User reports: "My agent isn't being invoked automatically"
1. Invoke docs-management skill
2. Use keywords: "automatic delegation agents", "agent description"
3. Check official docs for automatic invocation requirements
4. Guide user based on official troubleshooting steps
| Issue | Keywords for docs-management |
|---|---|
| Agent not found | "agent file locations", "agent directories" |
| Agent not auto-invoked | "automatic delegation", "agent description matching" |
| Wrong model used | "agent model selection", "inherit model" |
| Tools not available | "agent tools", "allowed-tools agents" |
| Resumption not working | "agent resumption", "resume agent" |
| Priority conflicts | "agent priority resolution", "project CLI user" |
This repository uses subagents for:
When creating agents for this repository, follow patterns in .claude/settings.json and existing agent configurations.
For comprehensive subagent usage guidance beyond configuration:
.claude/memory/operational-rules.md → "Agent Usage Principles".claude/memory/performance-quick-start.md → "Strategy 1: Parallelization".claude/memory/operational-rules.md → "Agent Communication Pattern"CLAUDE.md Quick Reference → "PROACTIVE DELEGATION"This skill provides the validation criteria used by the agent-auditor agent for formal audits.
| Resource | Location | Purpose |
|---|---|---|
| Validation Checklist | references/validation-checklist.md | Pre-creation verification checklist |
| Scoring Rubric | references/validation-checklist.md#audit-scoring-rubric | Formal audit scoring criteria |
| Undocumented Features | references/undocumented-features.md | Color, permissionMode, skills field details |
| Category | Points | Key Criteria |
|---|---|---|
| Name Field | 20 | Lowercase, hyphens, max 64 chars, no reserved words |
| Description Field | 25 | Third person, delegation triggers, when-to-use guidance |
| Tools Configuration | 20 | Appropriate restrictions, not over/under restricted |
| Model Selection | 15 | Appropriate for task complexity |
| Additional Fields | 20 | Color, skills, permissionMode correctly configured |
Thresholds: 85+ = PASS, 70-84 = PASS WITH WARNINGS, <70 = FAIL
The agent-auditor agent (Haiku model) performs formal audits using this skill:
skills: subagent-development/audit-agents commandOfficial Documentation (via docs-management skill):
Repository-Specific:
.claude/settings.json.claude/memory/performance-quick-start.md.claude/memory/operational-rules.md (Agent Usage Principles section)Date: 2025-11-28 Model: claude-opus-4-5-20251101