🏗️ Claude Agent Builder

Turn any idea into production-ready AI agents in Claude Code

Stop writing agent files from scratch. Describe your problem → get researched, architected, production-ready agents, skills, hooks, and commands — automatically.

Quick Start · How It Works · Examples · Patterns · Contributing

---

The Problem

Building agents in Claude Code means juggling 7 different primitives (subagents, skills, hooks, commands, MCP servers, CLAUDE.md, Agent SDK), reading scattered docs, and starting from blank Markdown files every time.

Claude Agent Builder fixes this. It's a skill that acts as your personal agent architect — it interviews you, researches what already exists, designs the optimal system, and generates every file you need.

⚡ Quick Start

macOS / Linux

git clone https://github.com/keysersoose/claude-agent-builder.git && cp -r claude-agent-builder/agent-builder ~/.claude/skills/

Windows (PowerShell)

git clone https://github.com/keysersoose/claude-agent-builder.git; Copy-Item -Recurse claude-agent-builder\agent-builder "$env:USERPROFILE\.claude\skills\agent-builder"

Windows (CMD)

git clone https://github.com/keysersoose/claude-agent-builder.git && xcopy /E /I claude-agent-builder\agent-builder "%USERPROFILE%\.claude\skills\agent-builder"

Other install methods

# macOS/Linux — install script
git clone https://github.com/keysersoose/claude-agent-builder.git
cd claude-agent-builder && ./install.sh

# macOS/Linux — project-level only
./install.sh --project

# Windows — install script (PowerShell)
git clone https://github.com/keysersoose/claude-agent-builder.git
cd claude-agent-builder; .\install.ps1

# Windows — project-level only
.\install.ps1 -Project

# Any platform — project-level manual
git clone https://github.com/keysersoose/claude-agent-builder.git
cp -r claude-agent-builder/agent-builder .claude/skills/

Open Claude Code and say:

Build me an agent that reviews my PRs for security issues and posts comments on GitHub

The skill triggers automatically. That's it.

🧠 How It Works

Agent Builder operates in 6 phases, adapting to how much context you provide:

  🔍 CONTEXT SCAN →  Reads your project files + conversation history automatically
  📋 DISCOVERY    →  Only asks what it can't figure out itself
  🌐 RESEARCH     →  Parallel search (GitHub + blogs + docs + community) → consolidated brief
  📐 ARCHITECTURE →  Proposes agents, gets your explicit approval before building
  🔨 BUILD        →  Writes all agent files directly into your project
  ✅ VERIFY       →  Self-checks everything, shows you what was built, asks for final OK

Why not just ask Claude directly?

Without Agent Builder	With Agent Builder
You need to know all 7 primitives	It picks the right ones for you
You write from blank .md files	It writes production-ready files directly into your project
You guess at descriptions and tools	It optimizes for auto-triggering
You explain your project from scratch	It scans your codebase and conversation history first
You don't know what exists already	It searches GitHub, blogs, docs, and community in parallel — then consolidates
Trial and error	Proposes → you approve → it builds → it verifies

📦 What's Inside

agent-builder/
├── SKILL.md                       # Core skill — 6-phase agent building workflow
├── references/
│   ├── primitives-guide.md        # Complete guide to all Claude Code building blocks
│   └── agent-patterns.md          # 7 battle-tested multi-agent architecture patterns
└── scripts/
    ├── validate_agents.py         # Lint agent files for common issues
    └── scaffold_agent.py          # Generate starter files from templates

🗺️ Architecture Patterns

The skill knows 7 proven patterns and selects the right one for your use case:

Pattern	Best For	Example
Command → Agent → Skills	Multi-step pipelines	Full-stack feature builder
Research → Consolidate → Plan → Execute	Understanding before acting	Codebase migration
Parallel Specialists	Independent analyses	Security + perf + style review
Self-Evolving Agent	Learning over time	Project onboarding guide
Hook-Guarded Agent	Safety-critical workflows	Read-only database analyst
Slash Command + Handoff	Quick entry → complex flow	Bug investigation
MCP-Powered Agent	External service integration	GitHub PR review bot

🎯 Real-World Examples

PR Security Reviewer — subagent with GitHub MCP, PreToolUse safety hooks, slash command trigger, and persistent memory.

Research Pipeline — /research command spawning 3 parallel subagents (web, codebase, Stack Overflow) with synthesis and markdown report output.

Self-Improving Onboarder — subagent with memory: project that builds institutional knowledge across conversations.

See examples/ for complete, ready-to-use configurations.

🔧 Utility Scripts

# Install dependency for validation script
pip install pyyaml

# Validate your agents for common issues
python agent-builder/scripts/validate_agents.py .claude/agents/

# Scaffold new agents from templates
python agent-builder/scripts/scaffold_agent.py my-agent .claude --type subagent
python agent-builder/scripts/scaffold_agent.py deploy-pipe .claude --type full-stack

Requirements: Claude Code installed. Python 3.7+ for utility scripts.

🧩 Primitives Decision Tree

Your need
├── "Auto-do X when Y happens"
│   ├── During a tool call?           → Hook
│   ├── Based on context?             → Skill
│   └── Based on task type?