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

Tool Access Patterns

Installation Locations

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