Stats
Actions
Tags
From claude-ecosystem
Guides Claude Code subagent development: agent files, YAML frontmatter, tool/model config, lifecycle/resumption, CLI/SDK usage, priority, built-in agents, troubleshooting via docs delegation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-ecosystem:subagent-developmentThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> ## 🚨 MANDATORY: Invoke docs-management First
🚨 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" |
| Hooks (v2.1.x) | "agent hooks", "hooks in agent", "agent PreToolUse", "agent PostToolUse" |
| 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: 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.
docs-management: "sub-agents.md configuration fields"
docs-management: "agent YAML frontmatter required optional"
| 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.
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" |
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:
.md files: *.md text eol=lf in .gitattributesfile *.md to check for CRLF before committing new agentsAfter Fix: Restart Claude Code session to pick up the corrected agent files.
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.
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 commandWhen auditing agents that use external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.
Technologies Requiring MCP Validation:
Validation Rule:
Never flag a technology usage as incorrect without first:
Stale Data Warning:
Official 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: 2026-01-10 Model: claude-opus-4-5-20251101
npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystemClaude Code subagent lifecycle: creation, configuration, evaluation, and troubleshooting. Invoke whenever task involves any interaction with Claude Code subagents — designing, debugging, iterating, or deciding when to delegate work to isolated agent contexts.
Guides creation and configuration of autonomous agents for Claude Code plugins, covering frontmatter, triggering descriptions, system prompts, tools, teams, permissions, and best practices.
Creates, validates, and refines Claude Code subagents for reliable delegation. Use for building new subagents, checking configurations, improving quality, scoping tool access, permission modes, and hook validation.