| name | subagent-factory |
| description | Create specialized Claude Code agents on-the-fly. Guides through agent definition file creation with proper frontmatter, effective prompts, and tool scoping. USE WHEN user says 'create agent', 'new subagent', 'make an agent for', 'build agent', 'spawn agent', or wants to define custom agents for specific tasks. |
Subagent Factory
Factory for creating specialized Claude Code agents. Generates agent definition files with proper configuration, effective system prompts, and appropriate tool access.
When to Activate This Skill
- User says: "create agent", "new subagent", "build agent"
- User wants: Custom agents for specific tasks
- User needs: Agent definition files, system prompts, tool configuration
- User asks: How to make specialized agents, how to delegate work
Two Creation Modes
Quick Mode (Direct Creation)
Fast path for experienced users. Minimal questions, direct file generation.
Use when: You know exactly what agent you need.
See: workflows/quick-create.md
Interview Mode (Guided Creation)
Interactive workflow with questions and customization at each step.
Use when: Exploring agent design, learning the process, or creating complex agents.
See: workflows/interview-create.md
Quick Reference: Agent Schema
Required Frontmatter Fields
---
name: agent-name
description: When to use this agent
---
Optional Frontmatter Fields
tools: Read, Write, Bash
model: sonnet
permissionMode: default
skills: skill-name
System Prompt (Markdown Body)
The Markdown content after frontmatter is the agent's system prompt.
Key elements:
- Identity/role definition
- Clear responsibilities
- Step-by-step workflow
- Concrete checklists
- Output format specification
- Boundaries (DO/DO NOT)
Core Principles
1. Single Responsibility
Each agent should have ONE clear purpose, not multiple loosely-related tasks.
2. Right Altitude
Not too prescriptive (brittle if-else logic), not too vague (unhelpful platitudes). Give clear guidance that lets the agent think.
3. Explicit Tool Scoping
Grant minimum necessary tools. Read-only agents don't need Write. Reviewers don't need Bash.
4. Progressive Examples
Include 3-5 concrete examples showing desired behavior patterns.
5. Actionable Instructions
Use imperative form: "Run tests", "Analyze code", "Generate report" (not "The tests are run").
Navigation
Deep Documentation
references/agent-schema.md - Complete frontmatter referencereferences/task-tool-reference.md - Task tool parameters and usagereferences/prompt-patterns.md - Effective prompt engineering patternsreferences/advanced-features.md - Hooks, slash commands, MCP integration
Workflows
workflows/quick-create.md - Fast agent creation stepsworkflows/interview-create.md - Interactive guided creation
Agent Types by Tool Access
Read-Only Agents (Reviewers, Auditors)
tools: Read, Grep, Glob
Use for: Code review, security audits, compliance checks
Research Agents (Analysts)
tools: Read, Grep, Glob, WebFetch, WebSearch, Write (if need to save research)
Use for: Technology research, documentation lookup, best practices
Code Writers (Implementers)
tools: Read, Write, Edit, Bash, Grep, Glob
Use for: Feature implementation, bug fixes, refactoring
Full-Stack Agents (End-to-End)
tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch
Use for: Complete feature delivery, integration work
Common Agent Patterns
Security Reviewer
Purpose: Analyze code for vulnerabilities
Tools: Read, Grep, Glob
Key checklist: Input validation, authentication, secrets, SQL injection, XSS, CSRF
Test Runner
Purpose: Execute tests, diagnose failures, propose fixes
Tools: Read, Edit, Write, Bash, Grep, Glob
Key workflow: Run tests → Diagnose failures → Propose fixes → Verify
Tech Researcher
Purpose: Investigate technologies, APIs, best practices
Tools: Read, Grep, Glob, WebFetch, WebSearch
Key output: Comparison matrix, recommendation with rationale, next steps
Code Implementer
Purpose: Build features following specifications
Tools: Read, Write, Edit, Bash, Grep, Glob
Key workflow: Understand requirements → Design → Implement → Test → Document
File Location
Agent definitions go in:
- Project-level:
.claude/agents/ (version controlled, team-shared)
- User-level:
~/.claude/agents/ (personal agents)
Precedence: Project agents override user agents with same name.
Task Tool Integration
Agents are invoked via the Task tool:
Use the security-reviewer agent to analyze the authentication module for vulnerabilities.
Built-in agent types:
general-purpose - Full tools, Sonnet modelexplore - Read-only, Haiku model (fast searches)plan - Research and analysis during planning
Custom agents: Reference by name from .claude/agents/
Parallel execution: Up to 10 concurrent agents (automatic queuing for more)
Key Insights
- System prompt is Markdown body, NOT frontmatter - Common mistake
- Tool inheritance - Omit
tools field to inherit all; specify to restrict
- Model selection - Use
haiku for fast searches, sonnet for balanced work, opus for complex reasoning
- Token overhead - Each agent spawn costs ~20k tokens; balance parallelization
- Context isolation - Each agent has independent context window (prevents cross-contamination)
Quick Start
Simple example:
# .claude/agents/test-runner.md
---
name: test-runner
description: Run tests, diagnose failures, propose fixes. Use after code changes.
tools: Read, Edit, Bash, Grep
model: sonnet
---
You are a test automation specialist.
## Workflow
1. Run test suite using project test command
2. If failures: capture output, read test files, diagnose root cause
3. Propose minimal fix with rationale
4. Re-run to verify
## Output Format
- Test results summary
- Failure analysis (if any)
- Proposed fixes with evidence
For detailed examples and patterns, see reference documentation.
Next Steps
- Choose creation mode (quick or interview)
- Define agent purpose and responsibilities
- Select appropriate tools
- Write effective system prompt
- Test with realistic scenarios
- Iterate based on failures
Start with workflows/quick-create.md for direct creation or workflows/interview-create.md for guided process.
