agent-factory

by @alirezarezvani in AI & LLM

427

# Install this skill:

npx skills add alirezarezvani/claude-code-skill-factory

Or install specific skill: npx add-skill https://github.com/alirezarezvani/claude-code-skill-factory/tree/dev/generated-skills/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

# SKILL.md

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

Generate Custom Agents - Create specialized agents for any domain (frontend, backend, testing, product, etc.)
Enhanced YAML Frontmatter - Rich metadata including color coding, field categorization, expertise levels
Tool Access Guidance - Recommends optimal tool configurations based on agent type
MCP Integration - Suggests relevant MCP server tools for enhanced capabilities
Execution Pattern Assignment - Ensures proper parallel/sequential execution for safety
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:

---
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

Open the prompt template: documentation/templates/AGENTS_FACTORY_PROMPT.md
Scroll to bottom - Find template variables
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
Copy entire prompt - Include filled variables
Paste into Claude - Claude.ai, Claude Code, or API
Receive agent file - Complete .md file ready to use
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:

---
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:

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

Keep agents focused - One clear responsibility per agent
Use descriptive descriptions - Enables auto-invocation
Follow tool access patterns - Match tools to agent type
Specify execution pattern - Prevents performance issues
Leverage MCP tools - Enhance agent capabilities
Test agents incrementally - Start simple, add complexity
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):

.claude/agents/custom-agent.md

Personal agents (available everywhere):

~/.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

# README.md

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
│   ├── aws-solution-architect/            # AWS architecture & IaC
│   ├── content-trend-researcher/          # Multi-platform content research
│   ├── ms365-tenant-manager/              # Microsoft 365 administration
│   ├── agent-factory/                     # Agent generation system
│   ├── prompt-factory/                    # Prompt generation powerhouse
│   ├── slash-command-factory/             # Slash command generation
│   ├── codex-cli-bridge/                  # Claude Code ↔ Codex CLI bridge
│   ├── hook-factory/                      # Claude Code hooks automation
│   └── claude-md-enhancer/                # CLAUDE.md generation & maintenance
├── generated-agents/                      # Specialized agents
│   └── claude-md-guardian/                # CLAUDE.md maintenance agent
└── generated-commands/                    # Custom slash commands
    └── enhance-claude-md/                 # CLAUDE.md enhancement command

🎁 Production Skills Included

All skills include complete implementation, documentation, samples, and distribution packages:

1. AWS Solution Architect (53 KB)

Serverless architecture, IaC templates, cost optimization
- View Skill

2. Content Trend Researcher (35 KB)

Multi-platform trend analysis, SEO-optimized outlines
- View Skill

3. Microsoft 365 Tenant Manager (40 KB)

M365 administration, PowerShell automation
- View Skill

4. Agent Factory (12 KB)

Generate custom Claude Code agents with enhanced YAML
- View Skill

5. Prompt Factory (427 KB)

69 professional presets, multi-format output, 7-point validation
- View Skill
- Most Popular - Install first for instant productivity

6. Slash Command Factory (26 KB)

17 presets, official Anthropic patterns, 4-layer validation
- View Skill

7. Codex CLI Bridge (48 KB)

Claude Code ↔ Codex CLI interoperability, AGENTS.md generation
- View Skill
- Enables cross-tool team collaboration

8. Hook Factory v2.0 (92 KB) 🆕

Build custom Claude Code hooks through interactive 7-question Q&A with automated installation and enhanced validation
- View Skill
- v2.0 - 10 production templates, automated installer (Python + Bash), secrets detection, event-specific validation

9. CLAUDE.md Enhancer (50 KB) 🆕

Analyze, generate, and enhance CLAUDE.md files with 100% native format compliance, interactive initialization, and automatic maintenance
- View Skill
- Ecosystem: Skill + Agent + Slash Command for complete CLAUDE.md lifecycle management
- Features: Interactive workflow, quality scoring (0-100), modular architecture, 7 built-in examples
- Companion Agent: claude-md-guardian - Background maintenance with auto-sync
- Slash Command: /enhance-claude-md - Initialize or enhance CLAUDE.md files

💡 Reference Examples

Three fully-functional example skills demonstrating different patterns:

Analyzing Financial Statements - Calculation engine + interpretation layer
Creating Financial Models - DCF valuation, sensitivity analysis, Monte Carlo simulation
Applying Brand Guidelines - Corporate branding application

See claude-skills-examples/ for implementation details.

✨ Key Features

Production-Ready Output - Proper YAML frontmatter, type-annotated Python, error handling
Interactive Workflows - Guided conversations through 4 specialist agents
Built-in Automation - 7 slash commands for common tasks
Complete Packaging - Documentation, samples, ZIP files included
Smart Detection - Automatically determines when Python code is needed vs prompt-only
Multi-Format Support - XML, Claude, ChatGPT, Gemini output formats
Official Patterns - Based on Anthropic documentation and examples
Cross-Platform - Works with Claude AI (desktop/browser), Claude Code, and API
Cross-Tool Compatibility - Bridge to OpenAI Codex CLI

📚 Documentation

Skills Guide: documentation/references/claude-skills-instructions.md - Complete Anthropic documentation
Agents Guide: documentation/references/claude-agents-instructions.md - Complete Anthropic documentation
Codex CLI Reference: documentation/references/openai-codex-cli-instructions.md - Complete OpenAI Codex CLI documentation
Slash Commands Examples: documentation/references/ - Official Anthropic examples
Factory Templates: documentation/templates/ - 4 generation templates
Project Guide: CLAUDE.md - Repository structure and workflows
Interactive Agents: .claude/agents/README.md - Guide agent documentation
Slash Commands: .claude/commands/README.md - Command reference

🔗 Complementary Resources

Claude Code Tresor - alirezarezvani/claude-code-tresor
- Ready-to-use development workflow tools (8 skills, 8 agents, 4 slash commands)
- Immediate productivity gains with proven patterns
- One-command installation

Claude Skills Library - alirezarezvani/claude-skills
- 37+ domain-specific production skills across 8 professional areas
- Marketing, Product, Engineering, C-Level Advisory expertise
- Battle-tested frameworks with proven ROI

How They Work Together:
- This Factory: Create custom skills/agents for unique requirements
- Tresor: Deploy ready-made development workflow tools
- Skills Library: Adopt domain-specific professional expertise

🌐 External Resources

Anthropic Skills Docs: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
Skills Marketplace: https://github.com/anthropics/skills
Engineering Blog: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
API Documentation: https://docs.claude.com/en/api/skills-guide

🤝 Contributing

This is a reference repository. To contribute:
1. Fork the repository
2. Add new example skills to claude-skills-examples/
3. Ensure skills follow formatting standards
4. Include complete implementation with samples
5. Submit a pull request

📄 License

This repository provides examples and templates for creating Claude Skills. The skills you generate using these templates are yours to use as you see fit.

📊 Version

Current Version: 1.4.0
Last Updated: October 30, 2025
Compatible With: Claude Skills (all platforms), Claude Code Agents, Claude Code Slash Commands

Latest Changes (v1.4.0):
- ✨ Added Codex CLI Bridge skill for Claude Code ↔ OpenAI Codex CLI interoperability
- ✨ Added /sync-agents-md and /codex-exec slash commands
- ✨ AGENTS.md auto-generation capability for cross-tool compatibility
- 📝 Consolidated README.md for better focus on main capabilities and shortcuts
- 🚀 Enhanced Quick Start with 3 shortcuts and workflow examples

Previous Changes (v1.3.0):
- MASTER_SLASH_COMMANDS_PROMPT.md template with official Anthropic patterns
- Slash Command Factory v2.0 with 17 presets and 4-layer validation
- Three official command patterns (Simple, Multi-Phase, Agent-Style)

Previous Changes (v1.2.0):
- Prompt Factory skill with 69 presets across 15 domains
- Multi-format output (XML/Claude/ChatGPT/Gemini)
- 7-point quality validation system

See: CHANGELOG.md for complete version history

📈 Star History

Ready to build? Try one of the shortcuts above, or explore the factory templates to start generating production-ready skills, agents, prompts, or slash commands!

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.