Subagent Creator for Claude Code

The /subagent-create command builds specialized AI subagents in Claude Code with custom expertise, independent context windows, and scoped tool permissions for modular multi-agent workflows.

Features

• Custom System Prompts: Define exact personality, expertise, and instructions per subagent
• Independent Context: Each subagent has isolated context window (doesn't clutter main conversation)
• Scoped Tool Access: Grant minimum required permissions per agent role
• Parallel Execution: Run up to 10 subagents concurrently with intelligent queuing
• Automatic Delegation: Claude intelligently selects subagents based on task context
• Template Library: Pre-built subagent templates for common development roles
• Performance Tracking: Monitor subagent success rates and execution times
• Result Aggregation: Combine outputs from multiple subagents into unified reports

Usage

/subagent-create [role] [options]

Subagent Roles (Pre-built Templates)

Development:

• --code-reviewer - Senior code reviewer and security expert
• --test-engineer - Test automation specialist
• --debugger - Debugging and troubleshooting expert
• --refactoring-specialist - Code refactoring and optimization
• --documentation-writer - Technical documentation specialist

Architecture:

• --architect - Software architect and system designer
• --database-expert - Database design and optimization
• --security-auditor - Security vulnerability assessment
• --performance-analyst - Performance optimization expert

DevOps:

• --ci-cd-engineer - CI/CD pipeline specialist
• --infrastructure-specialist - Cloud infrastructure expert
• --monitoring-expert - Observability and monitoring

Research:

• --researcher - Web research and data gathering
• --analyst - Data analysis and insights
• --technical-writer - Content creation and synthesis

Configuration Options

• --custom - Create custom subagent with manual configuration
• --tools=<list> - Grant specific tool access (comma-separated)
• --all-tools - Grant access to all available tools
• --read-only - Restrict to read-only tools only
• --parallel=<n> - Set max concurrent instances (default: 10)
• --context-size=<tokens> - Set context window size

Management Commands

• --list - List all configured subagents
• --status - Show active subagent execution status
• --delete=<name> - Remove subagent configuration
• --edit=<name> - Modify existing subagent

Examples

Code Review Subagent (Pre-built Template)

Command:

/subagent-create --code-reviewer

Generated Configuration:

{
  "name": "code-reviewer",
  "displayName": "Senior Code Reviewer",
  "description": "Reviews code for security, quality, and best practices",
  "systemPrompt": "You are a senior code reviewer with 15+ years of experience.\n\nYour expertise includes:\n- Security vulnerability detection (OWASP Top 10)\n- Code quality and maintainability assessment\n- Performance optimization identification\n- Best practices enforcement\n- Architecture and design patterns\n\nReview Guidelines:\n1. Identify security vulnerabilities with severity ratings\n2. Flag code smells and anti-patterns\n3. Suggest specific improvements with examples\n4. Praise good practices when found\n5. Consider the broader architectural context\n\nProvide constructive, actionable feedback.",
  "tools": ["read_file", "grep", "glob", "bash"],
  "capabilities": {
    "canWriteFiles": false,
    "canExecuteCommands": true,
    "canAccessNetwork": false
  },
  "maxConcurrent": 3,
  "contextWindowSize": 50000
}

Usage in Workflow:

User: "Review the authentication middleware for security issues"

Claude: *delegates to code-reviewer subagent*

Code Reviewer Subagent:
1. Reads src/middleware/auth.ts
2. Analyzes for vulnerabilities
3. Checks dependencies for known CVEs
4. Reviews error handling
5. Returns detailed security report

Claude: *presents aggregated findings to user*

Test Engineering Subagent

Command:

/subagent-create --test-engineer --tools=read_file,write_file,bash

Configuration:

{
  "name": "test-engineer",
  "displayName": "QA Test Engineer",
  "systemPrompt": "You are a QA engineer specializing in test automation.\n\nYour role:\n- Write comprehensive test suites (unit, integration, E2E)\n- Identify edge cases and test scenarios\n- Use Vitest, Jest, Playwright, Cypress\n- Ensure high code coverage (80%+ target)\n- Follow TDD best practices\n\nTest Philosophy:\n1. Tests should be deterministic and fast\n2. Mock external dependencies appropriately\n3. Use descriptive test names\n4. Follow AAA pattern (Arrange, Act, Assert)\n5. Test behavior, not implementation\n\nGenerate production-ready test code.",
  "tools": ["read_file", "write_file", "bash"],
  "capabilities": {
    "canWriteFiles": true,
    "canExecuteCommands": true
  }
}

Workflow Example:

User: "Create tests for the user authentication service"

Test Engineer Subagent:
1. Reads src/services/auth.service.ts
2. Identifies testable functions
3. Generates test file structure:
   - Unit tests for individual methods
   - Integration tests for auth flow
   - Edge cases (invalid tokens, expired sessions)
4. Writes tests/unit/auth.service.test.ts
5. Runs tests with: pnpm test auth.service
6. Reports coverage metrics

Custom Research Subagent

Command:

/subagent-create --custom

Interactive Setup:

Claude: "What should this subagent specialize in?"
User: "API documentation research and synthesis"

Claude: "What tools should it have access to?"
User: "web search, file reading, and writing"

Claude: "Generating custom subagent configuration..."

Generated Configuration:

{
  "name": "api-researcher",
  "displayName": "API Documentation Researcher",
  "systemPrompt": "You are an API documentation researcher specializing in discovering, analyzing, and synthesizing API documentation.\n\nYour capabilities:\n- Search for official API documentation\n- Analyze API endpoints, parameters, and responses\n- Identify authentication methods\n- Extract code examples\n- Synthesize findings into clear documentation\n\nDeliverables:\n1. Structured API reference documentation\n2. Authentication flow diagrams\n3. Code examples in multiple languages\n4. Common integration patterns\n5. Known limitations and best practices",
  "tools": ["web_search", "read_file", "write_file"],
  "capabilities": {
    "canAccessNetwork": true,
    "canWriteFiles": true
  }
}

Multi-Subagent Orchestration

Command:

/subagent-create --architect --code-reviewer --test-engineer --documentation-writer

Workflow: Building a New Feature

User: "Build a user notification system with email and push notifications"

Claude Orchestration:

1. Architect Subagent (parallel):
   - Designs system architecture
   - Defines data models
   - Specifies API contracts
   - Creates technical specification

2. Main Claude:
   - Implements notification service based on spec
   - Creates database migrations
   - Builds API endpoints

3. Code Reviewer Subagent (parallel):
   - Reviews implemented code
   - Identifies security issues
   - Suggests optimizations

4. Test Engineer Subagent (parallel):
   - Writes unit tests
   - Creates integration tests
   - Adds E2E test scenarios

5. Documentation Writer Subagent (parallel):
   - Generates API documentation
   - Writes integration guide
   - Creates troubleshooting section

Final Deliverable:
- Production-ready notification system
- Comprehensive test coverage
- Complete documentation
- Security-reviewed code

Debugging Workflow with Specialized Subagents

Command:

/subagent-create --debugger --performance-analyst

Scenario: Investigating Slow API Response

User: "The /api/users endpoint is taking 5+ seconds to respond"

Debugger Subagent:
1. Reproduces issue with curl/test requests
2. Analyzes server logs
3. Traces execution with console.log additions
4. Identifies slow database query
5. Reports findings: "N+1 query problem in user.posts relationship"

Performance Analyst Subagent (parallel):
1. Profiles database queries
2. Analyzes query execution plans
3. Identifies missing indexes
4. Benchmarks current vs optimized queries
5. Reports: "Adding index on posts.user_id reduces query time from 4.2s to 12ms"

Claude (main):
- Synthesizes findings from both subagents
- Implements fix: adds database index
- Applies eager loading to prevent N+1
- Runs benchmarks to verify 95% performance improvement

Security Audit with Multiple Specialists

Command:

/subagent-create --security-auditor --database-expert --code-reviewer

Workflow:

User: "Perform security audit of authentication system"

Security Auditor Subagent:
- Checks for SQL injection vulnerabilities
- Tests authentication bypass attempts
- Analyzes password hashing (bcrypt strength)
- Verifies JWT token validation
- Tests rate limiting effectiveness

Database Expert Subagent:
- Reviews database schema for PII exposure
- Checks for unencrypted sensitive fields
- Validates access control policies
- Tests for timing attacks on queries

Code Reviewer Subagent:
- Analyzes authentication code flow
- Identifies OWASP Top 10 vulnerabilities
- Reviews error handling (no info leakage)
- Validates input sanitization

Aggregated Report:
✓ Password hashing: bcrypt with cost 12 ✓
✗ CRITICAL: JWT tokens missing expiration
✗ HIGH: SQL query vulnerable to injection in login endpoint
⚠ MEDIUM: Missing rate limiting on password reset
✓ Session management secure ✓

Advanced Configuration

Tool Scoping (Minimum Permissions)

{
  "name": "security-auditor",
  "tools": [
    "read_file", // Can read code
    "grep", // Can search code
    "bash" // Can run security scanners
  ],
  "excludeTools": [
    "write_file", // CANNOT modify code
    "edit_file", // CANNOT edit files
    "web_search" // CANNOT access external resources
  ]
}

Context Window Optimization

{
  "name": "documentation-writer",
  "contextWindowSize": 100000, // Large context for full codebase understanding
  "summaryMode": true // Automatically summarize after each task
}

Parallel Execution Limits

{
  "name": "test-engineer",
  "maxConcurrent": 5, // Run up to 5 instances in parallel
  "queueStrategy": "fifo" // First-in-first-out when queue full
}

Handoff Patterns

{
  "name": "architect",
  "handoffs": ["code-reviewer", "test-engineer"],
  "handoffConditions": {
    "code-reviewer": "after implementation",
    "test-engineer": "after code review passes"
  }
}

Subagent Templates Library

Development Templates

Code Reviewer:

• Focus: Security, quality, best practices
• Tools: Read-only + bash for analysis
• Context: 50K tokens

Test Engineer:

• Focus: Test automation, coverage, TDD
• Tools: Read, write, bash
• Context: 50K tokens

Debugger:

• Focus: Bug reproduction, root cause analysis
• Tools: All tools except delete
• Context: 75K tokens

Refactoring Specialist:

• Focus: Code modernization, optimization
• Tools: Read, edit, write
• Context: 100K tokens

Architecture Templates

Software Architect:

• Focus: System design, scalability, patterns
• Tools: Read, write (specs only)
• Context: 100K tokens

Database Expert:

• Focus: Schema design, query optimization, migrations
• Tools: Read, write, bash (for DB tools)
• Context: 75K tokens

Security Auditor:

• Focus: Vulnerability assessment, penetration testing
• Tools: Read, bash (security scanners)
• Context: 50K tokens

Research Templates

Researcher:

• Focus: Information gathering, source verification
• Tools: Web search, read
• Context: 100K tokens

Analyst:

• Focus: Data analysis, pattern recognition, insights
• Tools: Read, bash (data tools)
• Context: 75K tokens

Technical Writer:

• Focus: Documentation, tutorials, API references
• Tools: Read, write
• Context: 100K tokens

Performance Metrics

Tracking Subagent Success

/subagent-create --status

Output:

Subagent Performance Report:

code-reviewer:
  Total Tasks: 45
  Success Rate: 93%
  Avg Execution Time: 12.3s
  Most Common Issues Found: Security (58%), Performance (22%)

test-engineer:
  Total Tasks: 38
  Success Rate: 89%
  Avg Execution Time: 24.7s
  Avg Coverage Generated: 84%

debugger:
  Total Tasks: 12
  Success Rate: 100%
  Avg Time to Root Cause: 3.2min

Best Practices

1. Principle of Least Privilege: Grant minimum required tools
2. Clear Role Definition: Specific, well-defined expertise areas
3. Independent Context: Keep subagent tasks isolated
4. Parallel When Possible: Run non-dependent tasks concurrently
5. Monitor Performance: Track success rates and optimize
6. Template First: Use pre-built templates before custom
7. Aggregate Results: Combine outputs for comprehensive reports
8. Version Control Config: Store subagent configs in .claude/agents/