Sub-Agent Creator

Automates creation of Claude Code sub-agents with proper configuration and proactive behavior.

When to Use

Trigger Phrases:

• "create a sub-agent for [purpose]"
• "generate a new sub-agent"
• "set up a sub-agent to handle [task]"
• "make a proactive agent that [behavior]"

Use Cases:

• Domain-specific agents (code reviewer, debugger)
• Proactive agents that auto-trigger on patterns
• Security-sensitive agents with limited tools
• Team-shared project-level agents

Workflow (6-Step Agent Creation Architect)

Follow this structured process for consistent, high-quality agents:

Step 1: Extract Core Intent

Identify what the agent should accomplish:

• Single responsibility: What ONE thing does this agent do?
• Trigger conditions: When should Claude invoke this agent?
• Success criteria: How do we know the agent succeeded?

Example:
- Intent: Review code for security vulnerabilities
- Trigger: Security-related requests, audit requests
- Success: Findings reported with confidence scores

Step 2: Design Expert Persona

Define the expertise the agent embodies:

• Domain expertise: What knowledge domain? (security, testing, DevOps)
• Perspective: Cautious? Thorough? Fast? Pragmatic?
• Communication style: Terse? Educational? Actionable?

Example:
- Persona: Senior security engineer with penetration testing background
- Perspective: Cautious, assumes hostile input
- Style: Concise findings with exploit paths

Step 3: Architect Instructions

Structure capabilities and constraints:

• PROHIBITED operations first (what it CANNOT do)
• ALLOWED operations second (what it CAN do)
• Output format specification
• Edge case handling

Structure order:
1. Prohibitions (safety rails)
2. Capabilities (what it does)
3. Output format (structured response)
4. Examples (when to use / when NOT)

Step 4: Optimize for Token Efficiency

Reduce prompt size without losing clarity:

• Remove redundant phrases
• Use tables over prose where possible
• Consolidate similar concepts
• Target: <500 tokens for focused agents, <1000 for complex

Step 5: Create Identifier

Generate the agent name:

• Format: lowercase, hyphenated, 2-4 words
• Pattern: [domain]-[action] or [action]-[target]
• Examples: security-reviewer, test-generator, migration-validator

Step 6: Add Examples

Provide dual-example training:

### When TO Use
<example>
user: "[request that should trigger]"
assistant: [Invokes agent]
<reasoning>Why this triggers</reasoning>
</example>

### When NOT to Use
<example>
user: "[request that should NOT trigger]"
assistant: [Does NOT invoke]
<reasoning>Why this doesn't trigger</reasoning>
</example>

---

Quick Workflow (Simplified)

For straightforward agents, use this condensed process:

Phase 1: Information Gathering

1. Purpose: What task/domain should agent specialize in?
2. Name: Auto-generate kebab-case from purpose
3. Description: Template: "Use PROACTIVELY to [action] when [condition]"
4. Location: Project (.claude/agents/) or User (~/.claude/agents/)

Phase 2: Technical Configuration

1. Model: inherit (default), sonnet, opus, haiku
2. Tools: Read-only, Code ops, Execution, All, Custom
3. System Prompt: Role, approach, priorities, constraints

Phase 3: File Generation

• Build YAML frontmatter
• Structure system prompt with templates
• Write to correct location

Phase 4: Validation & Testing

• Validate YAML, tools, model
• Generate testing guidance
• List customization points

Frontmatter Structure

---
name: agent-name
description: Use PROACTIVELY to [action] when [condition]
tools: Read, Grep, Glob  # Omit for all tools
model: sonnet             # Omit to inherit
---

Version Tracking (Recommended)

Pattern from: Claude Code version evolution

Track changes to enable rollback and understand evolution:

---
name: my-agent
changelog:
  - "0.3.0: Added anti-pattern examples"
  - "0.2.0: Enhanced with dual-example pattern"
  - "0.1.0: Initial release"
---

Versioning Guidelines:

• MAJOR (1.0.0): Breaking changes to behavior or output
• MINOR (0.1.0): New features, enhanced capabilities
• PATCH (0.0.1): Bug fixes, documentation updates

Keep changelog in frontmatter for quick reference; detailed notes can go in separate CHANGELOG.md.

Model Options

Model	Use Case
inherit	Same as main conversation (default)
sonnet	Balanced performance
opus	Maximum capability
haiku	Fast/economical

Tool Access Patterns

Pattern	Tools	Use Case
Read-only	Read, Grep, Glob	Safe analysis
Code ops	Read, Edit, Write	Modifications
Execution	Bash	Running commands
All	*	Full access (cautious)

Installation Locations

Location	Path	Use Case
Project	.claude/agents/	Team-shared, versioned
User	~/.claude/agents/	Personal, all projects

Success Criteria

• Valid YAML frontmatter
• Agent file in correct location
• Description includes "PROACTIVELY"
• System prompt has role, approach, constraints
• Appropriate tool restrictions
• Clear testing instructions

Security Best Practices

• Default to minimal tool access
• Require confirmation for "all tools"
• Validate tool list against available tools
• Warn about overly broad permissions

Reference Materials

• data/models.yaml - Model options
• data/tools.yaml - Available tools
• templates/agent-template.md - Prompt structure
• examples/ - Sample agents (code-reviewer, debugger)

Testing Your Agent

Manual Invocation

Use the [agent-name] sub-agent to [task]

Proactive Trigger

Perform action matching the description to test auto-delegation.

Debugging

# Check file
cat .claude/agents/[agent-name].md | head -10

# Verify location
ls .claude/agents/

---

Version: 0.1.0 | Author: Connor

Docs: https://docs.claude.com/en/docs/claude-code/sub-agents