🚨 MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about subagents/agents:

INVOKE docs-management skill

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.

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

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:

---
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:

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

Quick Decision Tree

What do you want to do?

Create a new agent -> Query docs-management: "agent file format", "agent YAML frontmatter"
Configure agent tools -> Query docs-management: "agent tools", "allowed-tools agents"
Select agent model -> Query docs-management: "agent model selection", "inherit sonnet haiku opus"
Configure permissionMode -> Query docs-management: "permissionMode", "agent permission mode"
Auto-load skills in agent -> Query docs-management: "agent skills field", "skills auto-load"
Understand automatic delegation -> Query docs-management: "automatic delegation agents"
Resume an agent (agentId) -> Query docs-management: "agent resumption", "agentId", "resumable agents"
Use /agents CLI -> Query docs-management: "/agents command", "agents CLI"
Programmatic agents (SDK) -> Query docs-management: "Agent SDK subagents"
Understand priority resolution -> Query docs-management: "agent priority resolution"
Work with General-purpose agent -> Query docs-management: "general-purpose subagent"
Work with Plan subagent -> Query docs-management: "Plan subagent", "planning agent"
Work with Explore subagent -> Query docs-management: "Explore subagent", "thoroughness levels"
Understand plugin agents -> Query docs-management: "plugin agents", "plugin-provided agents"
Chain multiple agents -> Query docs-management: "chaining subagents", "agent orchestration"
Optimize agent performance -> Query docs-management: "agent performance", "parallel agents"
Troubleshoot agent issues -> Query docs-management: "agent troubleshooting" + specific issue keywords
Add color to agent (undocumented) -> See "Color Property (Undocumented)" section above
Choose color for new agent -> See "Repository Color Standard" section above
Add lifecycle hooks to agent (v2.1.x) -> Query docs-management: "agent hooks", "hooks in agent frontmatter"

Topic Coverage

Agent Files

File format and structure
YAML frontmatter fields (name, description, tools, model)
File locations (project, CLI, user directories)
Naming conventions

Tool Configuration

Specifying allowed tools
Tool access inheritance
Restricting dangerous tools
MCP tools in agents

Model Selection

Model options: inherit, sonnet, haiku, opus
When to use each model
Cost and performance considerations
Inheritance from parent context

Invocation Patterns

Automatic delegation (description matching)
Explicit invocation via Task tool
Agent discovery and selection
Priority resolution order

Lifecycle Management

Agent execution flow
Context isolation
Result reporting
Error handling

Resumption

Resuming existing agents
Context preservation
When to resume vs create new
Resume parameter usage

CLI Integration

/agents command
Listing available agents
Agent status and management
CLI-defined agents

Agent SDK Integration

Programmatic agent creation
SDK patterns for subagents
Custom agent implementations
Advanced agent workflows

Default Agent Types

General-purpose subagent: Complex multi-step tasks, autonomous execution
Plan subagent: Implementation planning, architectural decisions
Explore subagent: Codebase exploration, read-only research
Thoroughness levels (quick, medium, very thorough) for Explore agent
Default agent behaviors and when to use each
Customizing built-in agent behavior

Plugin Agents

Plugin-provided agents
Plugin agent discovery and usage
Plugin agent configuration

Performance Considerations

Parallel agent execution
Context efficiency and token usage
Agent latency optimization
When to use subagents vs direct tools

Test Scenarios

These scenarios should activate this skill:

Direct activation: "Use the subagent-development skill to help me create an agent"
Configuration question: "How do I restrict tools for my subagent?"
Built-in agent question: "What is the Explore subagent and how do I use it?"
Troubleshooting: "My agent isn't being invoked automatically"
SDK question: "How do I define agents programmatically in the Agent SDK?"

Related Skills

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

Delegation Patterns

Standard Query Pattern

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

Multi-Topic Query Pattern

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

Troubleshooting Pattern

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

Troubleshooting Quick Reference

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"

Known Issues

CRLF Line Endings Cause Silent Loading Failures (v2.1.x)

GitHub Issues: #16916, #11205

Symptoms: Agent files exist but aren't available when spawning via Task tool. No error messages - agents silently fail to load.

Cause: Claude Code v2.1.x introduced stricter YAML parsing. Agent files with Windows-style CRLF line endings (\r\n) fail to parse correctly, causing the agent to be skipped during plugin loading.

Detection:

# Check if file has CRLF
file path/to/agent.md
# CRLF present: "ASCII text, with CRLF line terminators"
# LF only: "ASCII text" (no CRLF mention)

Fix:

# Convert CRLF to LF
sed -i 's/\r$//' path/to/agent.md

# Or using dos2unix
dos2unix path/to/agent.md

Prevention:

Configure Git to use LF for .md files: *.md text eol=lf in .gitattributes
Configure your editor to use LF for markdown files
Run file *.md to check for CRLF before committing new agents

After Fix: Restart Claude Code session to pick up the corrected agent files.

Plugin Agents Not Registered in plugin.json

Symptoms: Agent file exists in plugin's agents/ directory but isn't available when spawning via Task tool. No error messages.

Cause: The plugin's plugin.json uses an explicit agents array instead of directory auto-discovery. New agent files must be manually added to the array.

Detection:

# Check if plugin.json uses explicit array vs directory
grep -A 5 '"agents"' .claude-plugin/plugin.json
# Array: "agents": ["./agents/foo.md", ...]  <- Manual registration required
# Directory: "agents": "./agents"  <- Auto-discovery

Fix: Add the new agent file to the agents array in plugin.json.

Cross-reference: See plugin-development skill → "Component Registration in plugin.json" for detailed guidance on explicit vs auto-discovery modes.

Repository-Specific Notes

This repository uses subagents for:

Explore agents: Codebase exploration and research
Plan agents: Implementation planning
General-purpose agents: Complex multi-step tasks

When creating agents for this repository, follow patterns in .claude/settings.json and existing agent configurations.

Related Guidance

For comprehensive subagent usage guidance beyond configuration:

When to use subagents: See .claude/memory/operational-rules.md → "Agent Usage Principles"
Parallelization strategies: See .claude/memory/performance-quick-start.md → "Strategy 1: Parallelization"
Context preservation patterns: See .claude/memory/operational-rules.md → "Agent Communication Pattern"
Proactive delegation rule: See CLAUDE.md Quick Reference → "PROACTIVE DELEGATION"

Auditing Agents

This skill provides the validation criteria used by the agent-auditor agent for formal audits.

Audit Resources

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

Scoring Categories

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

Related Agent

The agent-auditor agent (Haiku model) performs formal audits using this skill:

Auto-loads this skill via skills: subagent-development
Uses validation checklist and scoring rubric
Checks both official and undocumented features
Generates structured audit reports
Invoked by /audit-agents command

External Technology Validation

When auditing agents that use external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.

Technologies Requiring MCP Validation:

.NET/C# scripts: Validate with microsoft-learn + perplexity
Node.js/npm packages: Validate with context7 + perplexity
Python scripts/packages: Validate with context7 + perplexity
Shell scripts: Validate with perplexity
Any version-specific claims: ALWAYS validate with perplexity

Validation Rule:

Never flag a technology usage as incorrect without first:

Querying appropriate MCP server(s) for current documentation
Verifying with perplexity for recent changes (especially .NET 10+)
Documenting MCP sources in the finding

Stale Data Warning:

microsoft-learn can return cached/outdated documentation
ALWAYS pair microsoft-learn with perplexity for version verification
Trust perplexity for version numbers and recently-released features

References

Official Documentation (via docs-management skill):

Primary: "sub-agents" documentation
Related: "Agent SDK", "Task tool", "model selection"

Repository-Specific:

Agent configurations: .claude/settings.json
Performance guidance: .claude/memory/performance-quick-start.md
Operational rules: .claude/memory/operational-rules.md (Agent Usage Principles section)

Version History

v1.4.0 (2026-01-10): Added Known Issues section
- Documented CRLF line ending issue causing silent agent loading failures in v2.1.x
- Documented plugin.json explicit array registration issue
- Added detection, fix, and prevention guidance for both issues
- Added cross-reference to plugin-development skill
- Referenced GitHub issues #16916 and #11205
v1.3.0 (2026-01-09): Added v2.1.x agent hooks keyword registry entry
- Added "Hooks (v2.1.x)" to Configuration keywords table
- Added Quick Decision Tree entry #20 for agent lifecycle hooks
v1.2.0 (2025-11-27): Color property documentation
- Added "Official YAML Frontmatter Reference" section with source reference to docs-management
- Added "Color Property (Undocumented)" section documenting available colors
- Added "Repository Color Standard" section with semantic color categories
- Added color keyword to Configuration registry
- Expanded Quick Decision Tree (19 entries, up from 17) with color entries
v1.1.0 (2025-11-27): Audit and enhancement
- Added missing keyword registry entries (permissionMode, skills field, plugin agents, chaining, performance)
- Expanded Built-in Agents section (General-purpose, Plan, Explore, thoroughness levels)
- Added Test Scenarios section (5 scenarios)
- Added Related Skills section
- Expanded Quick Decision Tree (17 entries, up from 10)
- Added Plugin Agents and Performance Considerations to Topic Coverage
- Added Token Budget statement
v1.0.0 (2025-11-26): Initial release
- Pure delegation architecture
- Comprehensive keyword registry
- Quick decision tree
- Topic coverage for all subagent features
- Troubleshooting quick reference

Last Updated

Date: 2026-01-10 Model: claude-opus-4-5-20251101

subagent-development

Subagents Meta Skill