Claude Code Subagent Development

Comprehensive guidance for creating, validating, and documenting Claude Code subagents with schemas and protocol specifications.

Purpose

This skill provides structured workflows for developing production-ready Claude Code subagents. Use when creating new subagents, validating existing configurations, generating JSON schemas for validation, or writing technical specifications for subagent protocols.

When to Use

This skill should be used when:

• Creating new subagent configurations
• Validating subagent YAML frontmatter and structure
• Generating JSON schemas for subagent validation
• Writing protocol specifications and technical documentation
• Reviewing subagent configurations for best practices
• Debugging subagent loading or invocation issues

Core Concepts

Subagent Structure

Subagents are Markdown files with YAML frontmatter:

markdown
---
name: subagent-identifier
description: When and how to use this subagent
tools: Tool1, Tool2
model: sonnet
permissionMode: default
skills: skill1, skill2
---

System prompt content in Markdown format.

Required Fields

• name: Lowercase identifier with hyphens (pattern: ^[a-z0-9-]+$)
• description: 10-2000 characters describing purpose and usage triggers
• content: Markdown body below frontmatter (implicit, not in frontmatter)

Optional Fields

• tools: Comma-separated list of allowed tools (inherits all if omitted)
• model: sonnet, opus, haiku, or inherit
• permissionMode: default, acceptEdits, bypassPermissions, plan, ignore
• skills: Comma-separated skill names to auto-load

Workflows

Create a New Subagent

1. Define purpose and scope:

• Identify the specific task or domain
• List concrete usage examples
• Determine required tools and permissions

1. Use the subagent template:

bash cp assets/template.md .claude/agents/your-subagent.md

1. Configure frontmatter:

• Set unique name (lowercase, hyphens)
• Write specific description with trigger phrases
• Specify minimal tools needed (or omit for all)
• Choose appropriate model and permissionMode

1. Write system prompt:

• Clear role definition
• Step-by-step procedures
• Expected behaviors and constraints
• Output format guidance

1. Validate configuration:

bash scripts/validate-subagent.sh .claude/agents/your-subagent.md

Validate Existing Subagent

Use the validation script to check:

• YAML frontmatter syntax
• Required fields present
• Field value formats (name pattern, model alias, etc.)
• Tool names validity
• Description quality

bash
scripts/validate-subagent.sh path/to/subagent.md

The script validates against the JSON schema in assets/subagent-schema.json.

Generate JSON Schema

When needing a validation schema for tooling:

1. Use the existing schema in assets/subagent-schema.json
2. Customize if needed for specific validation requirements
3. Integrate with CI/CD for automated validation

The schema includes:

• Field types and patterns
• Required vs optional fields
• Value constraints (enums, lengths, patterns)
• Examples and descriptions

Write Protocol Specification

For technical documentation:

1. Reference the protocol spec: references/protocol-specification.md
2. Include key sections:

• Architecture overview
• File format specification
• Configuration schema
• Lifecycle management
• Security considerations
• Examples

1. Adapt for your needs:

• Extract relevant sections
• Add project-specific details
• Include team conventions

Tools and Resources

Validation Script

scripts/validate-subagent.sh checks:

• File exists and is readable
• Valid YAML frontmatter
• Required fields present
• Name pattern compliance
• Model alias validity
• Tool name validation (optional check)

Usage:

bash
scripts/validate-subagent.sh <subagent-file>

Exit codes:

• 0: Valid configuration
• 1: Validation errors found

Creation Script

scripts/create-subagent.sh scaffolds a new subagent:

bash
scripts/create-subagent.sh <name> <scope>

Arguments:

• name: Subagent identifier (lowercase, hyphens)
• scope: project (.claude/agents/) or user (~/.claude/agents/)

Creates file from template and opens in editor.

JSON Schema

assets/subagent-schema.json provides:

• Complete field definitions
• Validation rules
• Type constraints
• Pattern matching
• Example configurations

Use with validation tools:

bash
# With ajv-cli
ajv validate -s assets/subagent-schema.json -d your-subagent.json

# With Python jsonschema
python -c "import json, jsonschema; \
  jsonschema.validate( \
    json.load(open('subagent.json')), \
    json.load(open('assets/subagent-schema.json')))"

Best Practices

Strong Descriptions

Include specific trigger phrases:

Good:

yaml
description: Expert code reviewer. Use PROACTIVELY after code changes to review quality, security, and best practices. Checks for vulnerabilities, performance issues, style violations.

Poor:

yaml
description: Helps with code

Minimal Tool Permissions

Grant only necessary tools:

yaml
# Read-only analysis
tools: Read, Grep, Glob

# Code modification
tools: Read, Edit, Write

# Full workflow
tools: Read, Edit, Write, Bash

Clear System Prompts

Structure prompts with:

1. Role definition
2. When invoked actions
3. Methodology/checklist
4. Output format
5. Examples

Model Selection

Choose appropriate model:

• haiku: Fast searches, simple tasks
• sonnet: General purpose, complex reasoning (default)
• opus: Maximum capability, critical tasks
• inherit: Match main conversation's model

Additional Resources

Reference Files

Comprehensive documentation in references/:

• protocol-specification.md: Complete subagent protocol spec (20,000+ words)
• Architecture and data flow
• File format specification
• All configuration fields detailed
• Lifecycle management
• Security considerations
• Built-in subagents reference

• field-reference.md: Detailed field-by-field reference
• Each field's purpose, format, constraints
• Examples and anti-patterns
• Common mistakes to avoid

• best-practices.md: Advanced best practices
• Design patterns for subagents
• Tool permission strategies
• Context management
• Team collaboration workflows

Example Files

Production-ready examples in examples/:

• code-reviewer.md: Comprehensive code review subagent
• Security, quality, performance checks
• Structured feedback format
• Tool usage: Read, Grep, Glob, Bash

• debugger.md: Systematic debugging specialist
• Root cause analysis methodology
• Strategic debugging techniques
• Common issue patterns

• test-runner.md: Test automation expert
• Auto-detect test frameworks
• Failure analysis and fixing
• Fast execution with Haiku

Asset Files

Templates and schemas in assets/:

• subagent-schema.json: Complete JSON Schema for validation
• template.md: Base template for new subagents

Quick Reference

Subagent File Locations

• Project scope: .claude/agents/name.md
• User scope: ~/.claude/agents/name.md
• Plugin scope: plugin-dir/agents/name.md

Precedence Order

When names conflict:

1. Project-level (highest)
2. User-level
3. CLI-defined
4. Built-in (lowest)

Available Tools

Common tools for subagents:

• Task - Delegate to subagents
• Bash - Execute shell commands
• Read, Edit, Write - File operations
• Grep, Glob - Search operations
• WebFetch, WebSearch - Web operations
• TodoWrite - Task management
• MCP tools: mcp__<server>__<tool>

Permission Modes

• default: Standard permission flow (recommended)
• acceptEdits: Auto-approve edit operations
• bypassPermissions: Skip all permissions (use cautiously)
• plan: Read-only exploration
• ignore: Ignore permission dialogs

Troubleshooting

Subagent Not Loading

Check:

1. File exists in correct location
2. Valid YAML frontmatter syntax
3. Required fields present (name, description)
4. Name follows pattern: ^[a-z0-9-]+$

Run validation:

bash
scripts/validate-subagent.sh path/to/subagent.md

Subagent Not Triggering

Improve description:

• Add specific trigger phrases users would say
• Include concrete scenarios
• Use emphatic language ("PROACTIVELY", "MUST BE USED")

Example:

yaml
description: Security auditor. Use PROACTIVELY when reviewing code, checking for vulnerabilities, or analyzing security. Checks OWASP Top 10, injection attacks, authentication issues.

Tool Not Available

Verify:

1. Tool name spelled correctly (case-sensitive)
2. Tool in allowed list if tools specified
3. MCP tool format: mcp__server__tool

Check available tools:

Task, Bash, Glob, Grep, Read, Edit, Write, NotebookEdit,
WebFetch, WebSearch, BashOutput, KillShell, AskUserQuestion,
TodoWrite, Skill, SlashCommand

Permission Denied

Adjust permissionMode:

• default: User approves operations
• acceptEdits: Auto-approve edits only
• bypassPermissions: Auto-approve all (use carefully)

Or grant specific tools in tools field.

Implementation Checklist

Before deploying a subagent:

Structure:

• ] Valid YAML frontmatter
• ] Required fields present (name, description)
• ] Markdown body substantial (50+ characters)
• ] File in correct location

Configuration:

• ] Name follows pattern ^[a-z0-9-]+$
• ] Description includes specific triggers
• ] Tools minimal but sufficient
• ] Model appropriate for task
• ] Permission mode suitable for automation level

Content Quality:

• ] Clear role definition
• ] Step-by-step procedures
• ] Concrete examples
• ] Expected output format
• ] Constraints and boundaries

Validation:

• ] Passes schema validation
• ] No YAML syntax errors
• ] Tool names valid
• ] Model alias correct

Testing:

• ] Triggers on expected queries
• ] Uses correct tools
• ] Produces quality output
• ] Respects permissions

Version History

• 1.0.0 (2025-12-03): Initial release
• Complete protocol specification
• JSON schema validation
• Validation and creation scripts
• Three production-ready examples
• Comprehensive reference documentation