subagent-factory

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                    # REQUIRED: kebab-case identifier
description: When to use this agent # REQUIRED: natural language triggers
---

Optional Frontmatter Fields

tools: Read, Write, Bash           # Comma-separated, omit to inherit all
model: sonnet                      # sonnet|opus|haiku|inherit
permissionMode: default            # Permission handling mode
skills: skill-name                 # Auto-load skills

System Prompt (Markdown Body)

The Markdown content after frontmatter is the agent's system prompt.

Key elements:

1. Identity/role definition
2. Clear responsibilities
3. Step-by-step workflow
4. Concrete checklists
5. Output format specification
6. 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 reference
• references/task-tool-reference.md - Task tool parameters and usage
• references/prompt-patterns.md - Effective prompt engineering patterns
• references/advanced-features.md - Hooks, slash commands, MCP integration

Workflows

• workflows/quick-create.md - Fast agent creation steps
• workflows/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
# Plus MCP tools as needed

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 model
• explore - 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

1. System prompt is Markdown body, NOT frontmatter - Common mistake
2. Tool inheritance - Omit tools field to inherit all; specify to restrict
3. Model selection - Use haiku for fast searches, sonnet for balanced work, opus for complex reasoning
4. Token overhead - Each agent spawn costs ~20k tokens; balance parallelization
5. 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

1. Choose creation mode (quick or interview)
2. Define agent purpose and responsibilities
3. Select appropriate tools
4. Write effective system prompt
5. Test with realistic scenarios
6. Iterate based on failures

Start with workflows/quick-create.md for direct creation or workflows/interview-create.md for guided process.