MUST load when building specialized subagents, configuring subagent settings, or understanding subagent execution model. Provides scaffolding templates, audit workflows, and structure standards for subagent creation.
Creates and configures specialized subagents with proper tool access and system prompts. Used when user asks to create, audit, or modify `.claude/agents/*.md` files for autonomous task execution.
/plugin marketplace add Git-Fg/thecattoolkit/plugin install git-fg-thecattoolkit@Git-Fg/thecattoolkitThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/templates/base-agent.mdassets/templates/coordinator-agent.mdassets/templates/explorer-agent.mdassets/templates/research-agent.mdassets/templates/specialized-agent.mdreferences/background-execution.mdreferences/context-management.mdreferences/context-reset.mdreferences/cross-platform.mdreferences/debugging-agents.mdreferences/error-handling-and-recovery.mdreferences/evaluation-and-testing.mdreferences/permissions-guide.mdreferences/skill-vs-subagent-decision.mdreferences/subagent-personas.mdreferences/subagents.mdreferences/writing-subagent-prompts.mdreferences/xml-markdown-framework.mdworkflows/audit.mdworkflows/create.mdDefault 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:
For detailed XML/Markdown guidelines, see:
User specifically asks to create, audit, or modify a Subagent (.claude/agents/*.md).
User asks about Skills or Commands.
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.
Use subagents for isolated context and specialized expertise:
When creating subagents, consider whether they will be invoked in background:
Background-safe subagents:
Background-unsafe subagents:
See references/background-execution.md for comprehensive guidance on background execution.
See references/context-reset.md for detailed guidance on context isolation.
.claude/agents/) for portability
Alternative: User-level (~/.claude/agents/) only if specifically requestedbrainstormer: 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.
| 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.
tools: Read, Grep, Glob, Bash)/agents interface to see all available toolsAvailable tools:
Read, Write, Edit - File operationsGlob, Grep - File searchBash - Execute shell commandsTodoWrite - Manage todo listsSkill, SlashCommand - Invoke skills and commandsTask - Delegate to subagentsWebSearch, WebFetch - Web accessBashOutput, KillShell - Background shell managementNotebookEdit - Jupyter notebook editingExitPlanMode - Plan mode controlPlus: 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.
sonnet, opus, haiku, or inheritinherit: uses same model as main conversationSubagents 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:
tools field is omitted or includes it)The main conversation sees only the subagent's final report/output.
Designing workflows with subagents:
Use main chat for:
Use subagents for:
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
Use the create workflow to create specialized subagents following Cat Toolkit best practices:
To modify an existing subagent:
Edit the subagent at: [path-to-subagent-file]
Use the edit workflow to:
To audit an existing subagent for best practices compliance:
Audit the subagent at: [path-to-subagent-file]
Use the audit workflow to evaluate:
For detailed XML/Markdown patterns and examples, see:
Clearly define the subagent's role, capabilities, and constraints.
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)
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.md files are system prompts. Use clear structure with markdown headings for organization.
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 workSimple subagents (single focused task):
Medium subagents (multi-step process):
Complex subagents (research + generation + validation):
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.
Claude automatically selects subagents based on the description field when it matches the current task.
You can explicitly invoke a subagent by referencing it in your instructions.
Run /agents for an interactive interface to:
You can also edit subagent files directly:
.claude/agents/subagent-name.md (project, portable)~/.claude/agents/subagent-name.md (if specifically requested)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:
coordinator-agent.mdresearch-agent.mdexplorer-agent.mdspecialized-agent.mdbase-agent.mdWHY: Templates ensure subagents follow consistent YAML frontmatter patterns, proper tool permissions, and clear role definitions.
Core references:
Subagent usage and configuration: references/subagents.md
Permissions and tools: references/permissions-guide.md
Background execution: references/background-execution.md
Writing effective prompts: references/writing-subagent-prompts.md
Advanced topics:
Evaluation and testing: references/evaluation-and-testing.md
Error handling and recovery: references/error-handling-and-recovery.md
Context management: references/context-management.md
Debugging and troubleshooting: references/debugging-agents.md
Decision guidance: references/skill-vs-subagent-decision.md
Cross-platform compatibility: references/cross-platform.md
A well-configured subagent has:
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.