Subagent Development

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

Configuration

Behavior

CLI and SDK

Built-in Agents

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

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

Reserved Colors (Future Use)

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 command", "agents CLI"
9. Programmatic agents (SDK) -> Query docs-management: "Agent SDK subagents"
10. Understand priority resolution -> Query docs-management: "agent priority resolution"
11. Work with General-purpose agent -> Query docs-management: "general-purpose subagent"
12. Work with Plan subagent -> Query docs-management: "Plan subagent", "planning agent"
13. Work with Explore subagent -> Query docs-management: "Explore subagent", "thoroughness levels"
14. Understand plugin agents -> Query docs-management: "plugin agents", "plugin-provided agents"
15. Chain multiple agents -> Query docs-management: "chaining subagents", "agent orchestration"
16. Optimize agent performance -> Query docs-management: "agent performance", "parallel agents"
17. Troubleshoot agent issues -> Query docs-management: "agent troubleshooting" + specific issue keywords
18. Add color to agent (undocumented) -> See "Color Property (Undocumented)" section above
19. Choose color for new agent -> See "Repository Color Standard" section above
20. 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:

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

Related Skills

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

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

Scoring Categories

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:

1. Querying appropriate MCP server(s) for current documentation
2. Verifying with perplexity for recent changes (especially .NET 10+)
3. 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.