spawn

What this skill does

# Spawn - Expert Agent Generator

Generate world-class, comprehensive expert agent prompts for Claude Code. Each agent should be a definitive reference for its domain - the kind of guide a PhD-level practitioner would create.

**Target quality:** 500-1000 lines per agent with real code examples, complete configs, and detailed patterns.

**Benchmark agents:** `python-expert.md` (1600 lines), `claude-architect.md` (1242 lines), `react-expert.md` (440 lines)

## Usage Modes

### Mode 1: Single Agent Generation
Generate one expert agent prompt for a specific technology platform.

**Prompt for:**
- Technology platform/framework name
- Scope (project-level or global/user-level)
- Focus areas (optional: specific features, patterns, use cases)
- Output format (markdown file or clipboard-ready text)

### Mode 2: Batch Agent Generation
Create multiple agent prompts from a list of technology platforms.

**Accept:**
- Multi-line list of technology platforms
- Scope (project-level or global/user-level)
- Common focus areas (optional)
- Output format (individual .md files or consolidated text)

### Mode 3: Architecture Analysis
Analyze a tech stack or architecture description and suggest relevant agents.

**Process:**
1. Read architecture description (from user input or file)
2. Identify all technology platforms/services
3. Ask for scope (project or global)
4. Present checkbox selector for agent creation
5. Generate selected agents

## Agent File Format

All agents MUST be created as Markdown files with **YAML frontmatter**:
- **Project-level**: `.claude/agents/` (current project only)
- **Global/User-level**: `~/.claude/agents/` or `C:\Users\[username]\.claude\agents\` (all projects)

**File Structure:**
```markdown
---
name: technology-name-expert
description: When this agent should be used. Can include examples and use cases. No strict length limit - be clear and specific. Include "use PROACTIVELY" for automatic invocation.
model: inherit
color: blue
---

[Agent system prompt content here]
```

**YAML Frontmatter Fields:**
- `name` (required): Unique identifier, lowercase-with-hyphens (e.g., "asus-router-expert")
- `description` (required): Clear, specific description of when to use this agent
  - No strict length limit - prioritize clarity over brevity
  - Can include examples, use cases, and context
  - Use "use PROACTIVELY" or "MUST BE USED" to encourage automatic invocation
  - Multi-line YAML string format is fine for lengthy descriptions
- `tools` (optional): Comma-separated list of allowed tools (e.g., "Read, Grep, Glob, Bash")
  - If omitted, agent inherits all tools from main session
  - **Best practice**: Only grant tools necessary for the agent's purpose (improves security and focus)
- `model` (optional): Specify model ("sonnet", "opus", "haiku", or "inherit" to use main session model)
- `color` (optional): Visual identifier in UI ("blue", "green", "purple", etc.)

**File Creation:**
Agents can be created programmatically using the Write tool:
```
Project-level: .claude/agents/[platform]-expert.md
Global/User-level: ~/.claude/agents/[platform]-expert.md (or C:\Users\[username]\.claude\agents\ on Windows)
```

**Choosing Scope:**
- **Project Agent** (`.claude/agents/`): Specific to the current project, can be version controlled and shared with team
- **Global Agent** (`~/.claude/agents/`): Available across all projects on your machine

After creation, the agent is immediately available for use with the Task tool.

## Claude Code Agent Documentation

**Essential Reading:**
- **Subagents Overview**: https://docs.claude.com/en/docs/claude-code/sub-agents
- **Subagents in SDK**: https://docs.claude.com/en/api/agent-sdk/subagents
- **Agent SDK Overview**: https://docs.claude.com/en/api/agent-sdk/overview
- **Agent Skills Guide**: https://docs.claude.com/en/docs/claude-code/skills
- **Agent Skills in SDK**: https://docs.claude.com/en/api/agent-sdk/skills
- **Skill Authoring Best Practices**: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices
- **Using Agent Skills with API**: https://docs.claude.com/en/api/skills-guide
- **Agent Skills Quickstart**: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart
- **Claude Code Settings**: https://docs.claude.com/en/docs/claude-code/settings
- **Common Workflows**: https://docs.claude.com/en/docs/claude-code/common-workflows
- **Claude Code Overview**: https://docs.claude.com/en/docs/claude-code/overview
- **Plugins Reference**: https://docs.claude.com/en/docs/claude-code/plugins-reference

**Key Concepts from Documentation:**
- Subagents operate in separate context windows with customized system prompts
- Each subagent can have restricted tool access for focused capabilities
- Multiple subagents can run concurrently for parallel processing
- User-level agents (`~/.claude/agents/`) are available across all projects
- Project-level agents (`.claude/agents/`) are project-specific and shareable
- Use `/agents` command for the recommended UI to manage agents
- Start with Claude-generated agents, then customize for best results
- Version control project-level subagents for team collaboration

## Generation Requirements

For each agent, create a comprehensive expert prompt with:

**Agent Content Structure (10-Part Template):**

Every generated agent MUST follow this comprehensive 10-part structure:


1. **Part 1: Core Concepts** - Fundamental principles, mental model, architecture overview
2. **Part 2: Essential Patterns** (5-10 patterns) - Each with: when to use, full implementation (20-50 lines), variations, common mistakes
3. **Part 3: Advanced Techniques** (3-5 techniques) - Deep dives with complete examples
4. **Part 4: Configuration** - Complete dev config, complete prod config, environment variables table
5. **Part 5: Integration Patterns** - Integration code for 2-3 common technologies
6. **Part 6: Testing Strategies** - Unit tests with mocks, integration tests, test configuration
7. **Part 7: Error Handling** - Custom exception hierarchy, retry/circuit breaker patterns, structured logging
8. **Part 8: Performance Optimization** - Profiling techniques, optimization table, caching strategies
9. **Part 9: Security Considerations** - Common vulnerabilities, security hardening checklist
10. **Part 10: Quick Reference** - Common operations cheat sheet (20-30 snippets), CLI commands, troubleshooting table

Plus: Quality Checklist, Anti-Patterns (5-10 with bad/good code), Canonical Resources (10-15 URLs)

See `python-expert.md` and `react-expert.md` in agents/ for reference implementations.

**Requirements:**
- YAML frontmatter at top with required fields (name, description)
- Concise, actionable system prompt (not verbose)
- Minimum 10 official/authoritative URLs
- Include real, production-ready code examples (10+ code blocks)
- Include complete configuration files (dev + prod)
- Include testing patterns with actual test code
- Focus on patterns, best practices, architecture
- Include canonical references for expansion
- Markdown formatted for direct use
- Description field can be lengthy with examples if needed for clarity

## Output Options

**Ask user to choose scope:**
1. **Project Agent** - Save to `.claude/agents/` (project-specific, version controlled)
2. **Global Agent** - Save to `~/.claude/agents/` or `C:\Users\[username]\.claude\agents\` (all projects)

**Ask user to choose format:**
1. **Clipboard-ready** - Output complete markdown (with YAML frontmatter) in code block
2. **File creation** - Use Write tool to save to appropriate agents directory based on scope
3. **Both** - Create file using Write tool AND show complete content in chat for review

**File Creation Process:**
When creating files programmatically:
1. Generate complete agent content with YAML frontmatter
2. Determine path based on scope selection:
   - Project: `.claude/agents/[platform-name]-expert.md`
   - Global: `~/.claude/agents/[platform-name]-expert.md` (or Windows equivalent)
3. Use Write to