Skip to main content
skill CX Codex

agent-factory — Claude Code skill: what it does, how to install

agent-factory generates production-ready Claude Code sub-agent files with YAML frontmatter, tool permissions, and MCP server integrations.

MIT ★ 907 updated 2025-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alirezarezvani/claude-code-skill-factory --skill agent-factory -a claude-code
Open on GitHub

What agent-factory does

The skill generates Markdown agent configurations intended for .claude/agents/ or ~/.claude/agents/. Each agent file includes extended YAML frontmatter defining domain areas, expertise levels, color tags, target models (sonnet, opus, haiku), and permitted tools such as Read, Write, Edit, or Bash.

Agent types follow strict concurrency boundaries to manage host workload. Strategic agents handle analysis and safely run 4–5 tasks in parallel. Implementation agents build features in groups of 2–3. Quality agents rely on heavy shell scripts and require sequential execution: running quality agents in parallel crashes the host system.

What it helps with

  • scaffold custom agent files with valid frontmatter for .claude/agents/
  • restrict tool access patterns based on agent specialization
  • configure external MCP tools like mcp__playwright or mcp__github
  • set safe concurrency boundaries across multiple sub-agents

Example prompts for the agent

  • Use @agent-factory to create a backend implementation agent with Read, Write, and Bash tools
  • Generate a code review agent file configured with mcp__github
  • Build a testing agent structure restricted to sequential execution

How to install agent-factory

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/agent-factory/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-factory/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-factory

How to install agent-factory in Claude Code?

Run npx skills add alirezarezvani/claude-code-skill-factory --skill agent-factory -a claude-code.

What does agent-factory do?

It creates standalone Markdown agent definitions complete with system instructions, frontmatter metadata, and tool configurations.

Why must quality agents run sequentially?

Quality agents execute resource-heavy Bash commands for test suites, which causes system crashes if run in parallel.

Source text

SKILL.md · MIT
---
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)

© alirezarezvani · MIT · alirezarezvani/claude-code-skill-factory

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set36

The whole set →
factory-status factory-status prints one report on everything the skill factory has produced so far: what passed checks, what is installed, and which step comes next. CX Codex +1 ★ 907repo stars install-hook Installs generated hooks into project or user settings files with safety checks and automatic backup creation. CX Codex +1 ★ 907repo stars sync-todos-to-github sync-todos-to-github turns a TodoWrite task list into a GitHub planning issue and starts follow-up automation. Useful for sprint plans and saved work checkpoints. CX Codex +1 ★ 907repo stars validate-output validate-output runs a checklist over a freshly generated skill, prompt, subagent or hook and names what needs fixing. A skill that passes gets zipped. CX Codex +1 ★ 907repo stars content-trend-researcher content-trend-researcher studies topic signals and audience intent across content platforms, then builds article outlines. Use it to validate ideas and spot underserved subjects. CX Codex +1 ★ 907repo stars sync-agents-md sync-agents-md rebuilds AGENTS.md from CLAUDE.md so the Claude CLI docs in a repo follow the project config. Handy after config edits or a new skill. CX Codex +1 ★ 907repo stars skills-guide Guides you through a quick questionnaire to build and package multi-file Claude skills with YAML frontmatter, Python code, and docs. CX Codex ★ 907repo stars codex-cli-bridge The codex-cli-bridge skill connects Claude Code projects with Codex CLI by creating AGENTS.md from CLAUDE.md and providing helpers to run Codex tasks. Use it when both tools are part of your workflow. CX Codex +1 ★ 907repo stars

Project sponsors

Companies that keep this analytics open