# agent-factory

Adopt this skill: https://proskills.md/skills/other/alirezarezvani-claude-code-skill-factory-generated-skills-agent-factory

Page: https://proskills.md/skills/other/alirezarezvani-claude-code-skill-factory-generated-skills-agent-factory
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: generated-skills/agent-factory/SKILL.md
size: 8172
sha: 3c340d030f0297e8c209a494afc17802e5556bf0
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/SKILL.md

````text
---
name: agent-factory
description: Claude Code agent generation system that creates custom agents and sub-agents with enhanced YAML frontmatter, tool access patterns, and MCP integration support following proven production patterns
---

# Agent Factory

A comprehensive system for generating production-ready Claude Code agents and sub-agents. This skill provides templates, standards, and generation tools to create custom agents that seamlessly integrate with Claude Code's agent system.

## What This Skill Does

This skill helps you create custom Claude Code agents for any domain or workflow. It generates properly formatted agent files that Claude Code can automatically discover and invoke when relevant.

### Capabilities

1. **Generate Custom Agents** - Create specialized agents for any domain (frontend, backend, testing, product, etc.)
2. **Enhanced YAML Frontmatter** - Rich metadata including color coding, field categorization, expertise levels
3. **Tool Access Guidance** - Recommends optimal tool configurations based on agent type
4. **MCP Integration** - Suggests relevant MCP server tools for enhanced capabilities
5. **Execution Pattern Assignment** - Ensures proper parallel/sequential execution for safety
6. **Validation** - Checks agent configuration against best practices

## Agent Types Supported

### Strategic Agents (Lightweight, Parallel-Safe)
- **Purpose**: Planning, research, analysis
- **Tools**: Read, Write, Grep only
- **Execution**: 4-5 agents can run in parallel
- **Color**: Blue
- **Examples**: product-planner, market-researcher, architect

### Implementation Agents (Full Tools, Coordinated)
- **Purpose**: Code writing, feature building
- **Tools**: Read, Write, Edit, Bash, Grep, Glob
- **Execution**: 2-3 agents coordinated
- **Color**: Green
- **Examples**: frontend-developer, backend-developer, api-builder

### Quality Agents (Heavy Bash, Sequential Only)
- **Purpose**: Testing, validation, review
- **Tools**: Read, Write, Edit, Bash, Grep, Glob
- **Execution**: 1 agent at a time (NEVER parallel)
- **Color**: Red
- **Examples**: test-runner, code-reviewer, security-auditor

### Coordination Agents (Lightweight, Orchestration)
- **Purpose**: Manages other agents, validates integration
- **Tools**: Read, Write, Grep
- **Execution**: Orchestrates others
- **Color**: Purple
- **Examples**: fullstack-coordinator, workflow-manager

## Enhanced YAML Frontmatter

Every generated agent includes rich metadata:

```yaml
---
name: agent-name-kebab-case
description: When to invoke this agent
tools: Read, Write, Edit  # Comma-separated
model: sonnet  # sonnet|opus|haiku|inherit
color: green  # Visual categorization
field: frontend  # Domain area
expertise: expert  # beginner|intermediate|expert
mcp_tools: mcp__playwright  # MCP integrations
---
```

### Field Categories

**Development**: `frontend`, `backend`, `fullstack`, `mobile`, `devops`
**Quality**: `testing`, `security`, `performance`
**Strategic**: `product`, `architecture`, `research`, `design`
**Domain**: `data`, `ai`, `content`, `finance`, `infrastructure`

### Color Coding

- **Blue**: Strategic/planning agents
- **Green**: Implementation/development agents
- **Red**: Quality/testing agents
- **Purple**: Coordination/orchestration agents
- **Orange**: Domain-specific specialists

### Expertise Levels

- **Beginner**: Simple, focused tasks
- **Intermediate**: Moderate complexity workflows
- **Expert**: Advanced, complex operations

## How to Use

### Quick Start

1. **Open the prompt template**: [documentation/templates/AGENTS_FACTORY_PROMPT.md](../../documentation/templates/AGENTS_FACTORY_PROMPT.md)
2. **Scroll to bottom** - Find template variables
3. **Fill in your details**:
   ```
   AGENT_NAME: my-custom-agent
   DESCRIPTION: What this agent does and when to invoke it
   DOMAIN_FIELD: frontend
   TOOLS_NEEDED: Read, Write, Edit, Bash
   ```
4. **Copy entire prompt** - Include filled variables
5. **Paste into Claude** - Claude.ai, Claude Code, or API
6. **Receive agent file** - Complete .md file ready to use
7. **Install agent** - Copy to `.claude/agents/` or `~/.claude/agents/`

### Example Invocation

```
@agent-factory

Create a custom agent:
Name: api-integration-specialist
Type: Implementation
Domain: backend
Description: API integration expert for third-party services
Capabilities: OAuth, REST clients, error handling
Tools: Read, Write, Edit, Bash
MCP: mcp__github
```

**Output**: Complete `.claude/agents/api-integration-specialist.md` file

## Generated Agent Structure

Each generated agent is a single Markdown file:

```markdown
---
name: custom-agent
description: Triggers auto-invocation
tools: Read, Write, Edit
model: sonnet
color: green
field: backend
expertise: expert
mcp_tools: mcp__github
---

You are a [role] specializing in [domain].

When invoked:
1. [Step 1]
2. [Step 2]
3. [Step 3]

[Detailed instructions]
[Checklists]
[Best practices]
[Output format]
```

## Integration Workflows

### Workflow 1: Feature Development
```
1. product-planner → Creates requirements
2. frontend-developer + backend-developer → Build (parallel)
3. test-runner → Validates (sequential)
4. code-reviewer → Reviews (sequential)
```

### Workflow 2: Bug Fix
```
1. debugger → Analyzes issue
2. [appropriate-dev-agent] → Fixes
3. test-runner → Validates fix
```

### Workflow 3: Code Review
```
1. code-reviewer → Quality review (can run solo)
2. security-auditor → Security scan (can run solo)
```

## MCP Tool Integration

Common MCP servers to integrate:

- **mcp__github**: PR reviews, issues, repo operations
- **mcp__playwright**: E2E testing, screenshots, browser automation
- **mcp__context7**: Documentation search, knowledge queries
- **mcp__filesystem**: Advanced file operations
- **Custom MCP servers**: Any user-configured MCP tools

Agents automatically reference MCP tools in their capabilities when configured.

## Safety & Performance

### Process Monitoring

Agents consume system resources. Monitor with:
```bash
ps aux | grep -E "mcp|npm|claude" | wc -l
```

**Safe ranges:**
- 15-20: Strategic agents (parallel)
- 20-30: Implementation agents (coordinated)
- 12-18: Quality agents (sequential)

**Warnings:**
- >30: Reduce parallelization
- >60: Critical - restart system

### Execution Rules

✅ **Safe**: 4-5 strategic agents in parallel
✅ **Safe**: 2-3 implementation agents coordinated
❌ **Unsafe**: Quality agents in parallel (crashes system)

## Best Practices

1. **Keep agents focused** - One clear responsibility per agent
2. **Use descriptive descriptions** - Enables auto-invocation
3. **Follow tool access patterns** - Match tools to agent type
4. **Specify execution pattern** - Prevents performance issues
5. **Leverage MCP tools** - Enhance agent capabilities
6. **Test agents incrementally** - Start simple, add complexity
7. **Version control agents** - Check project agents into git

## Limitations

- Agents are templates - customize for your specific needs
- Tool suggestions are guidelines, not requirements
- MCP tools require servers to be configured
- Performance depends on system resources
- Generated agents need testing in your environment

## Installation

**Generated Agent Files:**

Place in one of these locations:

**Project agents** (shared with team):
```bash
.claude/agents/custom-agent.md
```

**Personal agents** (available everywhere):
```bash
~/.claude/agents/custom-agent.md
```

## When to Use This Skill

**Create custom agents for:**
- Domain-specific workflows (data science, ML, finance)
- Team-specific conventions (your code style, testing approach)
- Specialized tools or frameworks (Shopify, AWS, Kubernetes)
- Custom MCP server integrations
- Rapid prototyping of agent ideas

**Use the AGENTS_FACTORY_PROMPT.md template when:**
- You need multiple related agents
- You want consistent agent patterns
- You're building an agentic framework
- You want to test agent concepts quickly

---

**Version**: 1.0.0
**Last Updated**: October 22, 2025
**Compatibility**: Claude Code (agents system)
**Template Location**: [documentation/templates/AGENTS_FACTORY_PROMPT.md](../../documentation/templates/AGENTS_FACTORY_PROMPT.md)
````

## File: generated-skills/agent-factory/agent_generator.py
size: 8192
sha: 06522d2fb1d370571c3c5d841951fd730130853c
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/agent_generator.py

```text
"""
Agent Generator
Creates Claude Code agent files with enhanced YAML frontmatter and validation.
"""

from typing import Dict, List, Any, Optional
import re

class AgentGenerator:
    """Generates Claude Code agent .md files with proper formatting."""

    # Color assignments by agent type
    COLOR_MAP = {
        "Strategic": "blue",
        "Implementation": "green",
        "Quality": "red",
        "Coordination": "purple",
        "Domain-Specific": "orange"
    }

    # Tool recommendations by agent type
    TOOL_RECOMMENDATIONS = {
        "Strategic": ["Read", "Write", "Grep"],
        "Implementation": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
        "Quality": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
        "Coordination": ["Read", "Write", "Grep"]
    }

    # Model recommendations
    MODEL_RECOMMENDATIONS = {
        "Strategic": "opus",  # Strategic thinking benefits from Opus
        "Implementation": "sonnet",  # Code generation works well with Sonnet
        "Quality": "sonnet",  # Testing and validation with Sonnet
        "Coordination": "opus"  # Orchestration benefits from Opus reasoning
    }

    def __init__(self):
        """Initialize agent generator."""
        pass

    def generate_agent(self, config: Dict[str, Any]) -> str:
        """
        Generate a complete agent .md file.

        Args:
            config: Agent configuration dictionary

        Returns:
            Complete agent file content as string
        """
        # Validate required fields
        self._validate_config(config)

        # Generate YAML frontmatter
        yaml_frontmatter = self._generate_yaml(config)

        # Generate system prompt
        system_prompt = config.get("system_prompt", "")

        # Combine into complete agent file
        agent_file = f"{yaml_frontmatter}\n{system_prompt}"

        return agent_file

    def _validate_config(self, config: Dict[str, Any]) -> None:
        """
        Validate agent configuration.

        Args:
            config: Configuration to validate

        Raises:
            ValueError: If configuration is invalid
        """
        required_fields = ["agent_name", "description"]

        for field in required_fields:
            if field not in config or not config[field]:
                raise ValueError(f"Required field '{field}' is missing")

        # Validate kebab-case name
        name = config["agent_name"]
        if not re.match(r'^[a-z]+(-[a-z]+)*$', name):
            raise ValueError(f"Agent name '{name}' must be in kebab-case (lowercase-with-hyphens)")

        # Validate agent type
        valid_types = ["Strategic", "Implementation", "Quality", "Coordination", "Domain-Specific"]
        agent_type = config.get("agent_type", "")
        if agent_type and agent_type not in valid_types:
            raise ValueError(f"Agent type must be one of: {', '.join(valid_types)}")

    def _generate_yaml(self, config: Dict[str, Any]) -> str:
        """
        Generate YAML frontmatter with enhanced fields.

        Args:
            config: Agent configuration

        Returns:
            YAML frontmatter as string
        """
        name = config["agent_name"]
        description = config["description"]

        # Get or infer tools
        tools = config.get("tools")
        if not tools:
            agent_type = config.get("agent_type", "Implementation")
            tools = ", ".join(self.TOOL_RECOMMENDATIONS.get(agent_type, ["Read", "Write", "Edit"]))
        elif isinstance(tools, list):
            tools = ", ".join(tools)

        # Get or infer model
        model = config.get("model")
        if not model:
            agent_type = config.get("agent_type", "Implementation")
            model = self.MODEL_RECOMMENDATIONS.get(agent_type, "sonnet")

        # Get or infer color
        color = config.get("color")
        if not color:
            agent_type = config.get("agent_type", "Implementation")
            color = self.COLOR_MAP.get(agent_type, "green")

        # Get field (domain)
        field = config.get("field", "general")

        # Get expertise level
        expertise = config.get("expertise", "intermediate")

        # Get MCP tools
        mcp_tools = config.get("mcp_tools", "")
        if isinstance(mcp_tools, list):
            mcp_tools = ", ".join(mcp_tools)

        # Build YAML frontmatter
        yaml_lines = [
            "---",
            f"name: {name}",
            f"description: {description}"
        ]

        # Add optional fields
        if tools:
            yaml_lines.append(f"tools: {tools}")

        if model:
            yaml_lines.append(f"model: {model}")

        yaml_lines.append(f"color: {color}")
        yaml_lines.append(f"field: {field}")
        yaml_lines.append(f"expertise: {expertise}")

        if mcp_tools:
            yaml_lines.append(f"mcp_tools: {mcp_tools}")

        yaml_lines.append("---")

        return "\n".join(yaml_lines)

    def validate_yaml_format(self, yaml_content: str) -> Dict[str, Any]:
        """
        Validate YAML frontmatter format.

        Args:
            yaml_content: YAML frontmatter content

        Returns:
            Validation result with errors if any
        """
        errors = []

        # Check for opening/closing ---
        if not yaml_content.startswith("---\n"):
            errors.append("YAML must start with '---'")

        if "\n---" not in yaml_content[4:]:
            errors.append("YAML must end with '---'")

        # Extract YAML content
        yaml_body = yaml_content.split("---")[1] if "---" in yaml_content else ""

        # Check for name field with kebab-case
        name_match = re.search(r'^name:\s*(.+)$', yaml_body, re.MULTILINE)
        if not name_match:
            errors.append("Missing 'name' field")
        elif name_match:
            name_value = name_match.group(1).strip()
            if not re.match(r'^[a-z]+(-[a-z]+)*$', name_value):
                errors.append(f"Name '{name_value}' must be kebab-case (lowercase-with-hyphens)")

        # Check for description
        if "description:" not in yaml_body:
            errors.append("Missing 'description' field")

        # Check tools format (comma-separated, not array)
        if "tools:" in yaml_body:
            tools_match = re.search(r'^tools:\s*(.+)$', yaml_body, re.MULTILINE)
            if tools_match:
                tools_value = tools_match.group(1).strip()
                if tools_value.startswith("[") or tools_value.startswith("{"):
                    errors.append("Tools must be comma-separated string, not array format")

        return {
            "valid": len(errors) == 0,
            "errors": errors
        }

def generate_agent_file(
    agent_name: str,
    description: str,
    system_prompt: str,
    agent_type: str = "Implementation",
    field: str = "general",
    tools: Optional[str] = None,
    model: Optional[str] = None,
    color: Optional[str] = None,
    expertise: str = "intermediate",
    mcp_tools: Optional[str] = None
) -> str:
    """
    Convenience function to generate an agent file.

    Args:
        agent_name: Kebab-case agent name
        description: When to invoke this agent
        system_prompt: Complete system prompt instructions
        agent_type: Strategic, Implementation, Quality, or Coordination
        field: Domain area
        tools: Comma-separated tool list (optional)
        model: Model to use (optional)
        color: Visual color coding (optional)
        expertise: beginner, intermediate, or expert
        mcp_tools: Comma-separated MCP tools (optional)

    Returns:
        Complete agent .md file content
    """
    config = {
        "agent_name": agent_name,
        "description": description,
        "system_prompt": system_prompt,
        "agent_type": agent_type,
        "field": field,
        "expertise": expertise
    }

    if tools:
        config["tools"] = tools
    if model:
        config["model"] = model
    if color:
        config["color"] = color
    if mcp_tools:
        config["mcp_tools"] = mcp_tools

    generator = AgentGenerator()
    return generator.generate_agent(config)
```

## File: generated-skills/agent-factory/expected_output.json
size: 1910
sha: 1fcfa38433b837d6c96b65d558c55e50b835272a
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/expected_output.json

```text
{
  "agent_file": ".claude/agents/api-integration-specialist.md",
  "file_content": "---\nname: api-integration-specialist\ndescription: API integration expert for connecting to third-party services. Use when building API clients or integrations.\ntools: Read, Write, Edit, Bash, Grep\nmodel: sonnet\ncolor: green\nfield: backend\nexpertise: expert\nmcp_tools: mcp__github\n---\n\nYou are an expert backend developer specializing in third-party API integrations.\n\nWhen invoked:\n1. Understand the API requirements and documentation\n2. Design clean client architecture\n3. Implement OAuth flows or API key auth\n4. Add comprehensive error handling\n5. Include retry logic with exponential backoff\n6. Write integration tests\n\nBest practices:\n- Use environment variables for secrets\n- Implement proper timeout handling\n- Add request/response logging\n- Cache responses when appropriate\n- Handle rate limits gracefully\n- Document all endpoints used\n\nFor each integration:\n- API client class or module\n- TypeScript types for requests/responses\n- Error handling for common failures\n- Integration tests\n- Usage documentation",
  "metadata": {
    "agent_name": "api-integration-specialist",
    "agent_type": "Implementation",
    "color": "green",
    "field": "backend",
    "expertise": "expert",
    "execution_pattern": "coordinated",
    "tool_count": 5,
    "mcp_integrations": ["mcp__github"]
  },
  "installation": {
    "project_level": "Copy to .claude/agents/api-integration-specialist.md",
    "user_level": "Copy to ~/.claude/agents/api-integration-specialist.md",
    "usage": "Agent auto-invokes when building API integrations, or invoke explicitly: 'Use api-integration-specialist agent to connect to Stripe API'"
  },
  "validation": {
    "yaml_format": "valid",
    "kebab_case": "valid",
    "tools_format": "valid (comma-separated)",
    "required_fields": "all present"
  }
}
```

## File: generated-skills/agent-factory/generated-agents/software-architect.md
size: 6855
sha: 3ca526c8bef04b9e542fcfc081024b4a0418d00b
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/generated-agents/software-architect.md

````text
---
name: software-architect
description: Software architecture and system design expert. Use for designing application architecture, making technical decisions, and creating architecture documentation.
tools: Read, Write, Grep
model: opus
color: blue
field: architecture
expertise: expert
---

You are a senior software architect specializing in system design, technical decision-making, and scalable architecture patterns.

When invoked:
1. Understand the application requirements and constraints
2. Research existing codebase and documentation
3. Design appropriate architecture pattern
4. Create comprehensive architecture documentation
5. Identify risks, trade-offs, and technical decisions
6. Provide implementation guidance

Architecture design process:

**1. Requirements Analysis**
- Functional requirements (what the system must do)
- Non-functional requirements (performance, scalability, security)
- Constraints (budget, timeline, existing systems)
- User scale and growth projections

**2. Architecture Pattern Selection**

Choose from proven patterns:
- **Monolithic**: Simple, single deployable unit
  - Best for: Small teams, early-stage products, simple requirements
  - Trade-offs: Easier to develop, harder to scale

- **Microservices**: Distributed, independently deployable services
  - Best for: Large teams, complex domains, independent scaling
  - Trade-offs: More complex, better isolation and scalability

- **Serverless**: Event-driven, fully managed infrastructure
  - Best for: Variable load, quick scaling, reduced ops overhead
  - Trade-offs: Vendor lock-in, cold starts, stateless design

- **Layered (N-tier)**: Presentation, Business, Data layers
  - Best for: Traditional enterprise apps, clear separation of concerns
  - Trade-offs: Well understood, can become tightly coupled

- **Event-Driven**: Async message-based communication
  - Best for: Real-time systems, loose coupling, high scalability
  - Trade-offs: Complexity, eventual consistency, debugging challenges

**3. Technology Stack Recommendations**

For each component recommend:
- **Frontend**: React, Next.js, Vue, Angular
- **Backend**: Node.js/Express, Python/FastAPI, Java/Spring, Go
- **Database**: PostgreSQL, MongoDB, Redis (caching)
- **Infrastructure**: AWS, GCP, Azure, Docker, Kubernetes
- **API**: REST, GraphQL, gRPC
- **Authentication**: JWT, OAuth 2.0, Auth0, Clerk
- **Deployment**: Vercel, Railway, AWS ECS, Kubernetes

**4. Architecture Documentation**

Create comprehensive documentation:

## Architecture Overview

### System Context
- **Purpose**: [What the system does]
- **Users**: [Who uses it]
- **Constraints**: [Technical/business constraints]

### High-Level Architecture

```
[Diagram or description of major components]

Frontend (React) ←→ API Gateway ←→ Backend Services ←→ Database
                         ↓
                    Message Queue
                         ↓
                  Background Workers
```

### Component Breakdown

**Frontend Layer:**
- Technology: React + TypeScript + Next.js
- Responsibilities: UI, user interactions, client-side routing
- Communication: REST API calls to backend

**API Layer:**
- Technology: Node.js + Express
- Responsibilities: Request routing, auth, rate limiting
- Endpoints: RESTful resources

**Business Logic Layer:**
- Technology: Node.js services or microservices
- Responsibilities: Core business logic, validation, orchestration
- Patterns: Service layer, domain models

**Data Layer:**
- Technology: PostgreSQL (primary), Redis (cache)
- Responsibilities: Data persistence, queries
- Schema: Normalized with relationships

**Infrastructure:**
- Hosting: AWS/GCP/Azure
- CI/CD: GitHub Actions
- Monitoring: DataDog, Sentry
- Deployment: Docker containers, orchestrated with Kubernetes or ECS

### Data Flow

1. User action in frontend
2. API request to backend
3. Authentication/authorization check
4. Business logic processing
5. Database operations
6. Response back to frontend
7. Async jobs queued for background processing

### Security Architecture

- **Authentication**: JWT tokens with refresh mechanism
- **Authorization**: Role-based access control (RBAC)
- **Data Protection**: Encryption at rest and in transit (TLS)
- **API Security**: Rate limiting, input validation, CORS
- **Secrets Management**: Environment variables, AWS Secrets Manager

### Scalability Strategy

- **Horizontal scaling**: Load balancer + multiple app instances
- **Database**: Read replicas, connection pooling
- **Caching**: Redis for frequent queries
- **CDN**: Static assets via CloudFront/Cloudflare
- **Async processing**: Message queue for heavy operations

### Technical Decisions & Trade-offs

Document key decisions:

**Decision**: Monolith vs Microservices
- **Choice**: Start with modular monolith
- **Reason**: Smaller team, faster iteration, can extract microservices later
- **Trade-off**: Accepting initial coupling for speed

**Decision**: SQL vs NoSQL
- **Choice**: PostgreSQL (SQL)
- **Reason**: ACID compliance, complex queries, relational data
- **Trade-off**: Less flexible schema, but data integrity guaranteed

**Decision**: REST vs GraphQL
- **Choice**: REST
- **Reason**: Simpler, well-understood, good enough for use case
- **Trade-off**: Multiple requests vs single GraphQL query, but lower complexity

### Risks & Mitigation

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Database bottleneck | High | Medium | Read replicas, caching, query optimization |
| Single point of failure | High | Low | Load balancing, auto-scaling, health checks |
| Security breach | Critical | Medium | Regular audits, penetration testing, security headers |

### Performance Requirements

- **Response time**: < 200ms for API calls (p95)
- **Availability**: 99.9% uptime
- **Concurrent users**: Support 10K simultaneous users
- **Data volume**: Handle 1M records with good performance

### Future Considerations

- **Phase 2**: Extract user service as microservice
- **Phase 3**: Add real-time features with WebSockets
- **Phase 4**: Multi-region deployment for global users

**5. Implementation Guidance**

Provide clear next steps:
- Folder structure recommendations
- Code organization patterns
- Development workflow
- Testing strategy
- Deployment pipeline

Output files:
- `documentation/foundation/architecture.md` - Complete architecture doc
- `documentation/foundation/tech-stack.md` - Technology decisions
- `documentation/foundation/adr/` - Architectural Decision Records (ADRs)

Best practices:
- Document all major technical decisions
- Create architecture diagrams (C4 model recommended)
- Consider trade-offs explicitly
- Plan for change and evolution
- Validate with prototypes for risky decisions

Use data and research to inform decisions. Balance ideal architecture with practical constraints.
````

## File: generated-skills/agent-factory/HOW_TO_USE.md
size: 9355
sha: dbd0502746d7873596cd4b13f77f7665032ea4f2
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/HOW_TO_USE.md

````text
# How to Use the Agent Factory

This guide shows you how to create custom Claude Code agents using the Agent Factory system.

## Quick Start

### Step 1: Open the Prompt Template

Navigate to: **[documentation/templates/AGENTS_FACTORY_PROMPT.md](../../documentation/templates/AGENTS_FACTORY_PROMPT.md)**

### Step 2: Scroll to Bottom

Find the template variables section:

```
=== FILL IN YOUR DETAILS BELOW ===

AGENT_TYPE: [Your choice]
AGENT_NAME: [kebab-case-name]
...
```

### Step 3: Fill In Your Details

```
AGENT_TYPE: Implementation
AGENT_NAME: api-integration-specialist
DOMAIN_FIELD: backend
DESCRIPTION: API integration expert for third-party services. Use when building API clients.
CAPABILITIES: OAuth flows, REST clients, error handling, rate limiting
TOOLS_NEEDED: Read, Write, Edit, Bash, Grep
MODEL: sonnet
COLOR: green
EXPERTISE_LEVEL: expert
MCP_TOOLS: mcp__github
SYSTEM_PROMPT: You are an expert backend developer...
NUMBER_OF_AGENTS: 1
```

### Step 4: Copy Entire Prompt

Copy the ENTIRE prompt template including your filled variables.

### Step 5: Generate with Claude

Paste into:
- **Claude.ai** (any plan)
- **Claude Code**
- **Claude API**

Claude will generate complete agent .md file(s).

### Step 6: Install Your Agent

**Project-level** (shared with team):
```bash
# Copy generated agent file
cp api-integration-specialist.md .claude/agents/

# Commit to git
git add .claude/agents/api-integration-specialist.md
git commit -m "Add API integration specialist agent"
```

**User-level** (personal, available everywhere):
```bash
# Copy to user agents folder
cp api-integration-specialist.md ~/.claude/agents/
```

### Step 7: Use Your Agent

**Automatic invocation**:
```
> Build a Stripe payment integration
```
(Claude automatically uses api-integration-specialist agent)

**Explicit invocation**:
```
> Use the api-integration-specialist agent to connect to the GitHub API
```

---

## Example Use Cases

### Example 1: Create a Test Automation Agent

**Fill template:**
```
AGENT_TYPE: Quality
AGENT_NAME: playwright-test-runner
DOMAIN_FIELD: testing
DESCRIPTION: Playwright E2E test specialist. Use after feature implementation.
CAPABILITIES: E2E tests, visual testing, test reports
TOOLS_NEEDED: Read, Write, Edit, Bash, Grep, Glob
EXECUTION_PATTERN: sequential
MODEL: sonnet
COLOR: red
EXPERTISE_LEVEL: expert
MCP_TOOLS: mcp__playwright
SYSTEM_PROMPT: You are a Playwright testing expert. Write and run E2E tests, generate reports, handle test failures.
NUMBER_OF_AGENTS: 1
```

**Generated agent**: `.claude/agents/playwright-test-runner.md`

**Usage**: "Run E2E tests for the checkout flow" → Agent auto-invokes

---

### Example 2: Create a Frontend Component Builder

**Fill template:**
```
AGENT_TYPE: Implementation
AGENT_NAME: react-component-builder
DOMAIN_FIELD: frontend
DESCRIPTION: React component specialist. Use for building reusable UI components.
CAPABILITIES: React components, TypeScript, styled-components, tests
TOOLS_NEEDED: Read, Write, Edit, Bash, Grep, Glob
EXECUTION_PATTERN: coordinated
MODEL: sonnet
COLOR: green
EXPERTISE_LEVEL: expert
MCP_TOOLS: mcp__playwright
NUMBER_OF_AGENTS: 1
```

**Usage**: "Build a ProductCard component" → Agent auto-invokes

---

### Example 3: Create Multiple Related Agents

**Fill template:**
```
AGENT_TYPE: Strategic, Implementation, Quality
NUMBER_OF_AGENTS: 3

Agent 1:
AGENT_NAME: feature-planner
DESCRIPTION: Feature planning specialist. Use for creating feature specs.
DOMAIN_FIELD: product
COLOR: blue
EXPERTISE_LEVEL: expert

Agent 2:
AGENT_NAME: fullstack-builder
DESCRIPTION: Full-stack developer. Use for implementing complete features.
DOMAIN_FIELD: fullstack
COLOR: green
EXPERTISE_LEVEL: expert

Agent 3:
AGENT_NAME: integration-tester
DESCRIPTION: Integration testing specialist. Use to validate feature integration.
DOMAIN_FIELD: testing
COLOR: red
EXPERTISE_LEVEL: expert
```

**Workflow**: Plan → Build → Test (complete feature pipeline)

---

## Enhanced YAML Fields Explained

### Color Coding

Choose color based on agent type:

| Color | When to Use | Examples |
|-------|-------------|----------|
| **blue** | Planning, research, strategy | product-planner, architect, researcher |
| **green** | Code writing, building | frontend-dev, backend-dev, api-builder |
| **red** | Testing, review, validation | test-runner, code-reviewer, qa-specialist |
| **purple** | Coordination, orchestration | fullstack-coordinator, workflow-manager |
| **orange** | Domain specialists | data-scientist, ml-engineer, finance-analyst |

### Field Categories

Organize by domain:

**Development**: `frontend`, `backend`, `fullstack`, `mobile`, `devops`
**Quality**: `testing`, `security`, `performance`, `quality`
**Strategic**: `product`, `architecture`, `research`, `design`
**Domain**: `data`, `ai`, `content`, `finance`, `infrastructure`

### Expertise Levels

- **beginner**: Simple tasks, limited scope (e.g., file-formatter, linter)
- **intermediate**: Moderate workflows (e.g., component-builder, api-tester)
- **expert**: Complex operations (e.g., system-architect, security-auditor)

### MCP Tools

Add comma-separated MCP server tools:

```yaml
mcp_tools: mcp__github, mcp__playwright, mcp__context7
```

Common integrations:
- `mcp__github` → PR reviews, issue management
- `mcp__playwright` → E2E testing, screenshots
- `mcp__context7` → Documentation search
- `mcp__filesystem` → Advanced file ops

---

## Tool Access Patterns

Follow these recommendations:

### Strategic Agents
```yaml
tools: Read, Write, Grep
color: blue
```
- Lightweight, parallel-safe
- No code execution

### Implementation Agents
```yaml
tools: Read, Write, Edit, Bash, Grep, Glob
color: green
```
- Full tool access
- Coordinated execution

### Quality Agents
```yaml
tools: Read, Write, Edit, Bash, Grep, Glob
color: red
```
- Heavy Bash operations
- **Sequential only!**

---

## Common Workflows

### Workflow 1: Full-Stack Feature

Create 3 agents:
1. **product-planner** (blue, strategic) → Requirements
2. **frontend-developer** (green, implementation) → UI
3. **backend-developer** (green, implementation) → API
4. **test-runner** (red, quality) → Validation

**Execution**:
- Step 1: Solo
- Steps 2-3: Parallel
- Step 4: Sequential

### Workflow 2: Bug Fix

Create 2 agents:
1. **debugger** (red, quality) → Find root cause
2. **code-fixer** (green, implementation) → Apply fix

**Execution**: Sequential

### Workflow 3: Code Review

Create 2 agents:
1. **code-reviewer** (red, quality) → Quality check
2. **security-auditor** (red, quality) → Security scan

**Execution**: Can run in parallel (both read-only)

---

## Tips for Success

### 1. Write Clear Descriptions

The `description` field is CRITICAL for auto-invocation:

✅ **Good**: "React component specialist. Use for building UI components."
❌ **Bad**: "Helps with frontend"

### 2. Keep Agents Focused

One agent, one job:

✅ **Good**: Separate `frontend-developer` and `backend-developer`
❌ **Bad**: One `fullstack-developer` that does everything

### 3. Follow Tool Patterns

Match tools to agent type for safety and performance.

### 4. Test Incrementally

Start with one simple agent, verify it works, then create more.

### 5. Use MCP When Available

If you have MCP servers configured, leverage them in your agents.

---

## Troubleshooting

### "My agent isn't being invoked automatically"

**Check description field**:
- Is it specific and action-oriented?
- Does it describe WHEN to use the agent?
- Try making it more explicit

### "YAML validation error"

**Common issues**:
- Name not in kebab-case
- Tools in array format `["Read"]` instead of comma-separated `Read, Write`
- Missing closing `---`

### "Agent crashes or freezes"

**Check execution pattern**:
- Quality agents MUST run sequential only
- Too many agents in parallel (>5)
- Check process count: `ps aux | grep claude | wc -l`

### "Tools not working"

**Verify**:
- Tools are comma-separated: `Read, Write, Edit`
- Not array format
- Tool names match exactly (case-sensitive)

---

## Installation Locations

### Project Agents (Shared with Team)
```
your-project/
└── .claude/
    └── agents/
        ├── custom-agent-1.md
        └── custom-agent-2.md
```

Commit to git - team gets them automatically.

### Personal Agents (Available Everywhere)
```
~/.claude/
└── agents/
    ├── my-personal-agent.md
    └── another-agent.md
```

Available across all your projects.

### Priority

When same name exists:
1. Project agents (highest priority)
2. Personal agents
3. Plugin agents (lowest priority)

---

## Next Steps

1. **Try the template** - Generate your first agent
2. **Install and test** - Verify it works
3. **Iterate** - Refine based on usage
4. **Create workflows** - Build complementary agents
5. **Share with team** - Commit project agents to git

---

## Reference

**Prompt Template**: [documentation/templates/AGENTS_FACTORY_PROMPT.md](../../documentation/templates/AGENTS_FACTORY_PROMPT.md)

**Claude Code Agents Documentation**: https://docs.claude.com/en/docs/claude-code/sub-agents

**Managing Agents**: Use `/agents` command in Claude Code

**Examples**: See `claude-agents-instructions.md` for complete examples

---

**Ready to create your first agent? Open the prompt template and start building!** 🚀
````

## File: generated-skills/agent-factory/sample_input.json
size: 1362
sha: 2542330409810307c6b7c68107809fb679015ced
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/generated-skills/agent-factory/sample_input.json

```text
{
  "agent_name": "api-integration-specialist",
  "agent_type": "Implementation",
  "description": "API integration expert for connecting to third-party services. Use when building API clients or integrations.",
  "field": "backend",
  "capabilities": [
    "OAuth 2.0 flows",
    "REST API client implementation",
    "Error handling and retry logic",
    "Rate limiting",
    "API response parsing"
  ],
  "tools": "Read, Write, Edit, Bash, Grep",
  "model": "sonnet",
  "color": "green",
  "expertise": "expert",
  "mcp_tools": "mcp__github",
  "system_prompt": "You are an expert backend developer specializing in third-party API integrations.\n\nWhen invoked:\n1. Understand the API requirements and documentation\n2. Design clean client architecture\n3. Implement OAuth flows or API key auth\n4. Add comprehensive error handling\n5. Include retry logic with exponential backoff\n6. Write integration tests\n\nBest practices:\n- Use environment variables for secrets\n- Implement proper timeout handling\n- Add request/response logging\n- Cache responses when appropriate\n- Handle rate limits gracefully\n- Document all endpoints used\n\nFor each integration:\n- API client class or module\n- TypeScript types for requests/responses\n- Error handling for common failures\n- Integration tests\n- Usage documentation",
  "execution_pattern": "coordinated"
}
```

## File: README.md
upstream: https://github.com/alirezarezvani/claude-code-skill-factory/blob/dev/README.md

````text
# Claude Code Skills & Agents Factory

A comprehensive toolkit for generating production-ready Claude Skills and Claude Code Agents at scale. This repository provides templates, examples, and powerful prompt engineering systems to create custom skills and specialized agents for Claude AI across all platforms.

## 🚀 Quick Start (3 Shortcuts)

### Shortcut 1: Interactive Builder (Fastest)
```
I want to build something
```
The **factory-guide** agent asks what you need and delegates to specialist guides.

### Shortcut 2: Use Slash Commands
```bash
/build skill              # Interactive skill builder
/build agent              # Interactive agent builder
/build prompt             # Interactive prompt builder
/build hook               # Interactive hook builder
```

### Shortcut 3: Use Ready-Made Skills
```bash
# Install Prompt Factory (69 professional presets)
cp -r generated-skills/prompt-factory ~/.claude/skills/

# Ask Claude
"I need a prompt for [role name]"
```

---

## 📋 Built-in Commands

This toolkit includes **10 slash commands** and **5 interactive agents** to streamline your workflow:

### Workflow Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `/build` | Interactive builder (skill/agent/prompt/hook) | `/build skill` or `/build hook` |
| `/build-hook` | Build Claude Code hooks (Q&A, alias) | `/build-hook` |
| `/validate-output` | Validate generated output + auto-ZIP | `/validate-output hook [path]` |
| `/install-skill` | Install skills to Claude Code | `/install-skill [path]` |
| `/install-hook` | Install hooks to settings | `/install-hook [path] [user\|project]` |
| `/test-factory` | Run test examples | `/test-factory` |
| `/factory-status` | Check system status (all factories) | `/factory-status` |
| `/sync-agents-md` | Generate AGENTS.md from CLAUDE.md | `/sync-agents-md` |
| `/codex-exec` | Execute Codex CLI commands | `/codex-exec analysis "task"` |
| `/sync-todos-to-github` | Convert TodoWrite tasks to GitHub issues | `/sync-todos-to-github "Sprint 12"` |

### Interactive Guide Agents

| Agent | Purpose | Activation |
|-------|---------|-----------|
| **factory-guide** | Orchestrator - delegates to specialists | "I want to build something" |
| **skills-guide** | Build Claude Skills (4-5 questions) | "Build a skill" |
| **prompts-guide** | Use Prompt Factory (69 presets) | "Generate a prompt" |
| **agents-guide** | Build Claude Code Agents (5-6 questions) | "Create an agent" |
| **hooks-guide** | Build Claude Code Hooks (5-7 questions) | "Build a hook" |

See [.claude/agents/README.md](.claude/agents/README.md) and [.claude/commands/README.md](.claude/commands/README.md) for complete documentation.

---

## 🎯 Main Capabilities

### 1. Skills Factory
Generate complete, production-ready Claude Skills with:
- Properly formatted SKILL.md with YAML frontmatter
- Python implementation files (when needed)
- Sample input/output data
- Complete documentation and usage guides
- ZIP packages for easy distribution

**Template**: [SKILLS_FACTORY_PROMPT.md](documentation/templates/SKILLS_FACTORY_PROMPT.md)
**Shortcut**: `/build skill` or "I want to build a skill"

### 2. Agents Factory
Create specialized Claude Code Agents with:
- Enhanced YAML frontmatter (name, description, tools, model, color, field, expertise)
- MCP integration support
- Auto-invocation capabilities
- Tool access configuration

**Template**: [AGENTS_FACTORY_PROMPT.md](documentation/templates/AGENTS_FACTORY_PROMPT.md)
**Shortcut**: `/build agent` or "I want to create an agent"

### 3. Prompt Factory
Generate mega-prompts for any role with:
- 69 professional presets across 15 domains
- Multiple output formats (XML, Claude, ChatGPT, Gemini)
- 7-point quality validation
- Core & Advanced modes

**Ready-to-use Skill**: [generated-skills/prompt-factory/](generated-skills/prompt-factory/)
**Shortcut**: Install skill, then "I need a prompt for [role]"

### 4. Hooks Factory
Generate Claude Code hooks for workflow automation with:
- 7 event types (SessionStart, PostToolUse, SubagentStop, etc.)
- Safety validation (tool detection, silent failure, no destructive ops)
- Language-specific templates (Python/Black, JS/Prettier, Rust/rustfmt, Go/gofmt)
- Interactive Q&A generation (5-7 questions)
- Automatic security checks before installation

**Template**: [HOOKS_FACTORY_PROMPT.md](documentation/templates/HOOKS_FACTORY_PROMPT.md)
**Implementation**: [generated-skills/hook-factory/](generated-skills/hook-factory/)
**Shortcut**: `/build hook` or "I want to build a hook"

### 5. Slash Command Factory
Create custom slash commands with:
- 17 preset commands (business, development, documentation, analysis)
- Three official Anthropic patterns (Simple, Multi-Phase, Agent-Style)
- Comprehensive 4-layer validation
- Auto-generated bash permissions

**Template**: [MASTER_SLASH_COMMANDS_PROMPT.md](documentation/templates/MASTER_SLASH_COMMANDS_PROMPT.md)
**Shortcut**: Use template directly or `/build` with custom workflow

### 6. Codex CLI Bridge
Enable Claude Code ↔ Codex CLI interoperability with:
- Automatic CLAUDE.md → AGENTS.md translation
- Reference-based architecture (no duplication)
- Safety mechanisms and auto-validation
- Cross-tool team collaboration support

**Skill**: [generated-skills/codex-cli-bridge/](generated-skills/codex-cli-bridge/)
**Shortcut**: `/sync-agents-md` to sync documentation

---

## 🔄 Complete Workflow Examples

### Example 1: Build a Skill in 2 Minutes
```bash
# Step 1: Start builder
/build skill

# Step 2: Answer 4-5 questions
# (Claude guides you through the process)

# Step 3: Validate output
/validate-output

# Step 4: Install
/install-skill

# Done! Your skill is ready to use
```

### Example 2: Generate Cross-Platform Prompt
```bash
# Step 1: Install Prompt Factory (one-time)
cp -r generated-skills/prompt-factory ~/.claude/skills/

# Step 2: Ask Claude
"I need a prompt for a Senior DevOps Engineer"

# Step 3: Answer 5-7 questions
# (Select format: XML, Claude, ChatGPT, or Gemini)

# Done! Copy and paste into your preferred LLM
```

### Example 3: Sync for Codex CLI Team
```bash
# Step 1: Ensure CLAUDE.md exists in your project
# (If missing, run /init first)

# Step 2: Generate AGENTS.md for Codex CLI users
/sync-agents-md

# Step 3: Commit to repo
git add AGENTS.md
git commit -m "docs: Add AGENTS.md for Codex CLI compatibility"

# Done! Codex CLI users can now reference your skills
```

---

## 📁 Repository Structure

```
claude-code-skills-factory/
├── README.md                              # This file
├── CLAUDE.md                              # Repository guidance
├── AGENTS.md                              # Codex CLI documentation (auto-generated)
├── CHANGELOG.md                           # Version history
├── .claude/
│   ├── agents/                            # 5 interactive guide agents
│   │   ├── factory-guide.md              # Orchestrator
│   │   ├── skills-guide.md               # Skills builder
│   │   ├── prompts-guide.md              # Prompts generator
│   │   ├── agents-guide.md               # Agents creator
│   │   └── hooks-guide.md                # Hooks builder
│   └── commands/                          # 8 slash commands
│       ├── build.md                       # Interactive builder
│       ├── build-hook.md                  # Hook builder
│       ├── validate-output.md             # Validation + ZIP
│       ├── install-skill.md               # Installation guide
│       ├── test-factory.md                # Test runner
│       ├── factory-status.md              # Status checker
│       ├── sync-agents-md.md              # CLAUDE.md → AGENTS.md
│       └── codex-exec.md                  # Codex CLI executor
├── claude-skills-examples/                # 3 reference implementations
├── documentation/
│   ├── references/                        # Official Anthropic examples
│   └── templates/                         # 4 factory prompt templates
├── generated-skills/                      # 9 production-ready skills
│   
````
