⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
agent-factory
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
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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
/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
# 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 and .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
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
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/ 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
Implementation: 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
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/
Shortcut: /sync-agents-md to sync documentation
🔄 Complete Workflow Examples
Example 1: Build a Skill in 2 Minutes
# 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
# 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
# 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
│
// HOW IT'S BUILT
// FILES
7 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
generated-skills/agent-factory/SKILL.md8.0 KB3c340d030f02upstream ↗
--- 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)generated-skills/agent-factory/agent_generator.py8.0 KB06522d2fb1d3upstream ↗
""" 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)generated-skills/agent-factory/expected_output.json1.9 KB1fcfa38433b8upstream ↗
{ "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" } }generated-skills/agent-factory/generated-agents/software-architect.md6.7 KB3ca526c8bef0upstream ↗
--- 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.generated-skills/agent-factory/HOW_TO_USE.md9.1 KBdbd0502746d7upstream ↗
# 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!** 🚀generated-skills/agent-factory/sample_input.json1.3 KB254233040981upstream ↗
{ "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" }README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/alirezarezvani-claude-code-skill-factory-generated-skills-agent-factory.md