Core Principle

Default to Pure Markdown. Most subagents work well with simple Markdown structure (## Role, ## Workflow, ## Constraints). Add XML tags only when complexity genuinely requires it (multi-phase state tracking, critical safety constraints).

Use the XML/Markdown decision framework:

• Pure Markdown (0 tags): Default for simple, linear workflows
• Hybrid XML/Markdown (1-5 tags): When AI needs to organize multiple pathways, track state, or enforce critical constraints

For detailed XML/Markdown guidelines, see:

• XML/Markdown Framework

Activation Triggers

WHEN

User specifically asks to create, audit, or modify a Subagent (.claude/agents/*.md).

WHEN NOT

User asks about Skills or Commands.

Objective

Subagents are specialized Claude instances that run in isolated contexts with focused roles and limited tool access. This skill teaches you how to create effective subagents, write strong system prompts, configure tool access, and work with specialized subagents.

Subagents enable complex tasks to be handled by specialized agents that operate autonomously without user interaction, returning their final output to the main conversation.

Quick Start

When to Create a Subagent

Use subagents for isolated context and specialized expertise:

1. Separate Context Required: Deep thinking and analysis
2. System Maintenance: Maintaining AI infrastructure
3. Specialized Expertise: Domain-specific knowledge

Background Execution Considerations

When creating subagents, consider whether they will be invoked in background:

Background-safe subagents:

• Use read-only tools (Read, Grep, Glob) - safest
• Have pre-approved tool access
• Don't require user interaction
• Provide exhaustive context in task prompt

Background-unsafe subagents:

• Use Bash or Write tools without pre-approval
• Require user interaction or confirmation
• Perform destructive operations

See references/background-execution.md for comprehensive guidance on background execution.

See references/context-reset.md for detailed guidance on context isolation.

Workflow

1. Default: Project-level (.claude/agents/) for portability Alternative: User-level (~/.claude/agents/) only if specifically requested
2. Define the subagent:
   • name: lowercase-with-hyphens
   • description: "[Role]. MUST/PROACTIVELY USE when [trigger condition]"
   • tools: Optional comma-separated list
   • skills: List relevant skills
3. Write system prompt using normal conversational language
4. Test with real delegation

Subagent Persona Example

brainstormer: Strategic thinking specialist

---
name: brainstormer
description: Strategic Thinking Specialist. PROACTIVELY USE when deep reasoning, strategic analysis, or framework-based problem solving requires isolated context.
tools: Read, Write, Edit, Glob, Grep, Bash, TodoWrite, SlashCommand
skills: thinking-frameworks
---

## Role

You are a strategic thinking engine tasked with deep reasoning and strategic analysis. You operate in an isolated context when delegated complex reasoning tasks to keep the user's main chat focused. Your primary tool is the `thinking-frameworks` skill.

## Process

1. **Understand Context**: Thoroughly read the user's request...
2. **Select Framework**: Choose the most appropriate framework...
3. **Apply Framework**: Invoke the skill to access and apply...
4. **Present Results**: Structure the output clearly...

## Purpose

This agent provides a separate context window for deep, structured thinking and analysis, keeping the main chat clean while enabling comprehensive problem-solving.

See references/subagent-personas.md for more examples.

File Structure

Type	Location	Scope	Priority
Project (default)	.claude/agents/	Current project only, portable	Highest
User (if requested)	~/.claude/agents/	All projects	Lower
Plugin	Plugin's agents/ dir	All projects	Lowest

Project-level subagents override user-level when names conflict. Use project location for portability.

Configuration

Name Field

• Lowercase letters and hyphens only
• Must be unique

Description Field

• Natural language description of purpose
• Include when Claude should invoke this subagent
• Used for automatic subagent selection

Tools Field

• Optional - Comma-separated list of tools (e.g., tools: Read, Grep, Glob, Bash)
• If omitted: inherits all tools from main thread
• Use /agents interface to see all available tools

Available tools:

• Read, Write, Edit - File operations
• Glob, Grep - File search
• Bash - Execute shell commands
• TodoWrite - Manage todo lists
• Skill, SlashCommand - Invoke skills and commands
• Task - Delegate to subagents
• WebSearch, WebFetch - Web access
• BashOutput, KillShell - Background shell management
• NotebookEdit - Jupyter notebook editing
• ExitPlanMode - Plan mode control

Plus: MCP tools from configured MCP servers can also be specified.

Critical: Subagents can use AskUserQuestion if configured via the tools field. If tools is omitted, they inherit all tools including AskUserQuestion. If tools is specified, AskUserQuestion must be explicitly included.

Model Field

• sonnet, opus, haiku, or inherit
• inherit: uses same model as main conversation
• IMPORTANT: Omit this field by default to keep subagents generalist
• Only specify a model if the user explicitly requests it or if the task requires specific model capabilities
• If omitted: defaults to configured subagent model (usually sonnet)

Execution Model

Critical Constraint

Subagents are black boxes that CAN interact with users, but intermediate steps are hidden.

Subagents run in isolated contexts and return their final output to the main conversation. They:

• ✅ Can use tools like Read, Write, Edit, Bash, Grep, Glob
• ✅ Can access MCP servers and other non-interactive tools
• ✅ CAN use AskUserQuestion to gather input or clarification (if tools field is omitted or includes it)
• ❌ User never sees subagent's intermediate steps (only final output)

The main conversation sees only the subagent's final report/output.

Workflow Design

Designing workflows with subagents:

Use main chat for:

• Gathering requirements from user (AskUserQuestion)
• Presenting options or decisions to user
• Any task requiring user confirmation/input
• Work where user needs visibility into progress

Use subagents for:

• Research tasks (API documentation lookup, code analysis)
• Code generation based on pre-defined requirements
• Analysis and reporting (security review, test coverage)
• Context-heavy operations that don't need user interaction

Example workflow pattern:

Main Chat: Ask user for requirements (AskUserQuestion)
  ↓
Subagent: Research API and create documentation (no user interaction)
  ↓
Main Chat: Review research with user, confirm approach
  ↓
Subagent: Generate code based on confirmed plan
  ↓
Main Chat: Present results, handle testing/deployment

Workflows

Create New Subagent

Use the create workflow to create specialized subagents following Cat Toolkit best practices:

• Identifies valid use cases for isolated context
• Defines clear subagent personas
• Uses normal conversational language
• Lists relevant skills in YAML
• Creates context reset guidance

Edit Existing Subagent

To modify an existing subagent:

Edit the subagent at: [path-to-subagent-file]

Use the edit workflow to:

• Update subagent personas or descriptions
• Modify tool access or skill references
• Refine workflow steps or constraints
• Add new capabilities or refine existing ones

Audit Existing Subagent

To audit an existing subagent for best practices compliance:

Audit the subagent at: [path-to-subagent-file]

Use the audit workflow to evaluate:

• YAML frontmatter quality (name, description, tools, skills)
• Role definition clarity and specialization
• Workflow specification presence and clarity
• Constraints definition with strong boundaries
• Contextual judgment based on complexity

For detailed XML/Markdown patterns and examples, see:

• XML/Markdown Framework

System Prompt Guidelines

Be Specific

Clearly define the subagent's role, capabilities, and constraints.

Use Clear Structure

Structure the system prompt clearly. Use markdown headings for general structure, XML for highly structured elements like workflows:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
---

## Role

You are a senior code reviewer specializing in security.

## Focus Areas

- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure

## Workflow

1. Read the modified files
2. Identify security risks
3. Provide specific remediation steps
4. Rate severity (Critical/High/Medium/Low)

Task-Specific

Tailor instructions to the specific task domain. Don't create generic "helper" subagents.

❌ Bad: "You are a helpful assistant that helps with code" ✅ Good: "You are a React component refactoring specialist. Analyze components for hooks best practices, performance anti-patterns, and accessibility issues."

Subagent Structure

Subagent.md files are system prompts. Use clear structure with markdown headings for organization.

Recommended Structure

Common sections for subagent structure:

• ## Role - Who the subagent is and what it does
• ## Constraints - Hard rules (NEVER/MUST/ALWAYS)
• ## Focus Areas - What to prioritize
• ## Workflow - Step-by-step process
• ## Output Format - How to structure deliverables
• ## Success Criteria - Completion criteria
• ## Validation - How to verify work

Intelligence Rules

Simple subagents (single focused task):

• Use role + constraints + workflow minimum
• Example: api-researcher, test-runner

Medium subagents (multi-step process):

• Add workflow steps, output format, success criteria
• Example: api-researcher, documentation-generator

Complex subagents (research + generation + validation):

• Add all sections as appropriate including validation, examples
• Example: mcp-api-researcher, comprehensive-auditor

Formatting Guidance

Use markdown headings for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).

For structure principles, invoke the manage-skills skill if deeper guidance on skill organization is needed.

Invocation

Automatic

Claude automatically selects subagents based on the description field when it matches the current task.

Explicit

You can explicitly invoke a subagent by referencing it in your instructions.

Management

Using /agents Command

Run /agents for an interactive interface to:

• View all available subagents
• Create new subagents
• Edit existing subagents
• Delete custom subagents

Manual Editing

You can also edit subagent files directly:

• Default: .claude/agents/subagent-name.md (project, portable)
• Alternative: ~/.claude/agents/subagent-name.md (if specifically requested)

Templates Index

MANDATORY: When creating or editing subagents, always read and use the appropriate template from assets/templates/.

Subagent templates in assets/templates/:

Template	Use Case
base-agent.md	Simple, focused subagent with basic role and minimal structure
specialized-agent.md	Domain-specific expertise with focused knowledge areas
coordinator-agent.md	Multi-step orchestration, coordinates multiple subagents/subtasks
research-agent.md	Research, analysis, and verification with systematic methodology
explorer-agent.md	Read-only code exploration, safe for background execution

Template Selection Logic:

1. Orchestration/multi-step workflows → coordinator-agent.md
2. Research/analysis/verification → research-agent.md
3. Read-only exploration/background-safe → explorer-agent.md
4. Domain-specific expertise → specialized-agent.md
5. Otherwise → base-agent.md

WHY: Templates ensure subagents follow consistent YAML frontmatter patterns, proper tool permissions, and clear role definitions.

Reference Guides

Core references:

Subagent usage and configuration: references/subagents.md

• File format and configuration
• Model selection (Sonnet 4.5 + Haiku 4.5 orchestration)
• Tool security and least privilege
• Prompt caching optimization
• Complete examples
• Background execution invocation

Permissions and tools: references/permissions-guide.md

• Comprehensive tool permissions documentation
• Available tools and syntax
• Security considerations
• When to specify tools vs. inherit all
• Background execution considerations

Background execution: references/background-execution.md

• Background vs foreground execution
• Permission constraints for background agents
• Risk assessment and safety matrix
• Cross-platform considerations

Writing effective prompts: references/writing-subagent-prompts.md

• Core principles and XML structure
• Description field optimization for routing
• Extended thinking for complex reasoning
• Security constraints and strong modal verbs
• Success criteria definition

Advanced topics:

Evaluation and testing: references/evaluation-and-testing.md

• Evaluation metrics (task completion, tool correctness, robustness)
• Testing strategies (offline, simulation, online monitoring)
• Evaluation-driven development
• G-Eval for custom criteria

Error handling and recovery: references/error-handling-and-recovery.md

• Common failure modes and causes
• Recovery strategies (graceful degradation, retry, circuit breakers)
• Structured communication and observability
• Anti-patterns to avoid

Context management: references/context-management.md

• Memory architecture (STM, LTM, working memory)
• Context strategies (summarization, sliding window, scratchpads)
• Managing long-running tasks
• Prompt caching interaction

Debugging and troubleshooting: references/debugging-agents.md

• Logging, tracing, and correlation IDs
• Common failure types (hallucinations, format errors, tool misuse)
• Diagnostic procedures
• Continuous monitoring

Decision guidance: references/skill-vs-subagent-decision.md

• When to use skills vs subagents
• Decision matrix and key principles
• Deduplication guidelines
• Domain expertise vs isolated context

Cross-platform compatibility: references/cross-platform.md

• Platform-specific considerations
• Feature availability and compatibility
• Best practices for cross-platform agents

Success Criteria

A well-configured subagent has:

• Valid YAML frontmatter (name matches file, description includes triggers)
• Clear role definition in system prompt
• Appropriate tool restrictions (least privilege)
• Well-structured system prompt with role, approach, and constraints
• Description field optimized for automatic routing
• Successfully tested on representative tasks
• Model selection appropriate for task complexity (Sonnet for reasoning, Haiku for simple tasks)