Claude Command and Control

Comprehensive instruction manuals, templates, and best practices for creating Claude commands, configuring AI agents, and orchestrating multi-agent workflows.

GitHub Actions Status

📑 Table of Contents

📚 Overview

The Claude Command and Control repository is the definitive resource for building robust, production-ready AI agent systems. Whether you're creating simple slash commands or complex multi-agent orchestrations, this manual provides the patterns, templates, and best practices you need.

What You'll Find Here

📖 Comprehensive Manuals: Seven interconnected documents covering every aspect of command and agent creation
🎯 Ready-to-Use Templates: Production-tested templates for common commands and agent roles
🏗️ Architecture Patterns: Proven orchestration patterns for multi-agent workflows
🔒 Security Best Practices: Guidelines for safe, controlled AI agent operations
✅ Quality Standards: Testing, validation, and maintenance strategies
🚀 Production Guidance: Deployment, monitoring, and lifecycle management

📂 Repository Structure

claude-command-and-control/
├── .claude/
│   ├── commands/              # 13 active production commands
│   ├── agents/                # General agent configurations
│   └── skills/
│       └── registry.json      # Skill discovery and metadata
│
├── docs/
│   ├── best-practices/        # 15 comprehensive instruction manuals
│   │   ├── 01-Introduction-and-Core-Principles.md
│   │   ├── 02-Individual-Command-Creation.md
│   │   ├── 03-Individual-Agent-Configuration.md
│   │   ├── 04-Multi-Agent-Orchestration.md
│   │   ├── 05-Testing-and-Quality-Assurance.md
│   │   ├── 06-Production-Deployment-and-Maintenance.md
│   │   ├── 07-Quick-Reference-and-Templates.md
│   │   ├── 08-Claude-Skills-Guide.md
│   │   ├── 09-Agent-Skills-vs-Multi-Agent.md
│   │   ├── 10-Developing-High-Impact-Claude-Skills.md
│   │   ├── 11-hybrid-ai-agent-multi-git-worktree-development.md
│   │   ├── 12-Skills-First-Planning-and-Orchestration.md
│   │   ├── 13-Pict-BDD-Test-Design.md
│   │   ├── 14-LLM-Production-Optimization.md
│   │   └── 15-Advanced-Orchestration-Patterns.md
│   ├── references/            # Anthropic specifications and guides
│   │   ├── agent-skills-specification.md
│   │   ├── agent-skills-overview.md
│   │   └── agent-skills-integration-guide.md
│   └── TEMPLATE_CUSTOMIZATION.md
│
├── commands-templates/        # 21 base + 6 orchestration = 27 command templates
│   ├── orchestration/         # Multi-agent orchestration commands (basic)
│   │   ├── coordinate-workflow.md
│   │   ├── orchestrate-feature.md
│   │   ├── quality-gate.md
│   │   ├── spawn-agents.md
│   │   └── worktree-setup.md
│   ├── cleanup.md             # Workspace cleanup automation
│   ├── close-session.md       # Session summary and push
│   ├── create-skill.md        # Skill generation from docs/GitHub/PDFs
│   ├── deps-update.md         # Dependency audit and updates
│   ├── docs.md                # Documentation generation
│   ├── env-check.md           # Environment health validation
│   ├── error-report.md        # Diagnostic report generation
│   ├── handoff.md             # Work state handoff documentation
│   ├── lint-fixes.md          # Auto-fix code style issues
│   ├── plan.md                # Project planning document generation
│   ├── pr.md                  # Pull request creation workflow
│   ├── search.md              # Codebase search with ranking
│   ├── start-session.md       # Context loading and session init
│   ├── summarize.md           # Change summarization
│   └── test-all.md            # Comprehensive test suite execution
│
├── agents-templates/          # 10 base + 6 orchestration = 16 specialized agent configurations
│   ├── orchestration/         # Advanced orchestration agents (NEW in v1.1)
│   │   ├── dag-orchestrator.md          # DAG execution with topological sorting
│   │   ├── orchestrator-lead.md         # Multi-agent workflow coordination
│   │   ├── performance-monitor.md       # Performance profiling and optimization
│   │   ├── pool-manager.md              # Dynamic agent pool management
│   │   ├── resilience-orchestrator.md   # Saga pattern and circuit breakers
│   │   ├── state-manager.md             # Distributed state with CRDTs
│   │   ├── task-coordinator.md          # Task dependency resolution
│   │   ├── integration-orchestrator.md  # Result synthesis and merging
│   │   └── monitoring-agent.md          # Real-time progress tracking
│   ├── general-agent-skills-first.md    # Generic skills-first agent template (NEW)
│   ├── architect.md           # System design and planning (v2.0 consolidated)
│   ├── builder.md             # Implementation with TDD
│   ├── devops.md              # Infrastructure and CI/CD
│   ├── integration-manager.md # Content ingestion system
│   ├── maintenance-manager.md # Repository health management
│   ├── researcher.md          # Technical research (v2.0 consolidated)
│   ├── scribe.md              # Documentation creation
│   └── validator.md           # Testing and security audits
│
├── skills/                    # 20 production-ready skills
│   ├── agent-skill-bridge/    # Agent-skill integration patterns
│   ├── architect-role-skill/  # Architecture design workflows
│   ├── builder-role-skill/    # TDD implementation workflows
│   ├── content-research-writer/ # Research + citation workflows
│   ├── devops-role-skill/     # Infrastructure workflows
│   ├── documentation-update/  # Automated doc updates
│   ├── file-categorization/   # File type classification
│   ├── researcher-role-skill/ # Research workflows
│   ├── root-cause-tracing/    # Systematic debugging
│   ├── scribe-role-skill/     # Documentation workflows
│   ├── sharing-skills/        # Skill contribution via PR
│   ├── skill-creator/         # New skill generation
│   ├── skill-orchestrator/    # Multi-skill coordination
│   ├── software-architecture/ # Architecture documentation
│   ├── subagent-driven-development/ # Isolated subagent execution
│   ├── superpowers-lab/       # Meta-skill experimentation
│   ├── ui-ux-pro-max/         # 50+ UI/UX design patterns
│   ├── using-git-worktrees/   # Isolated workspace management
│   ├── using-superpowers/     # Skill discovery and invocation
│   └── validator-role-skill/  # Testing workflows
│
├── skills-templates/          # 31 base + 6 orchestration = 37 skill templates
│   ├── orchestration/         # Advanced orchestration skill templates (NEW in v1.1)
│   │   ├── agent-pool-manager-skill.md        # Auto-scaling, health monitoring
│   │   ├── circuit-breaker-skill.md           # Cascading failure prevention
│   │   ├── distributed-state-sync-skill.md    # CRDT implementations
│   │   ├── performance-profiler-skill.md      # Token usage profiling
│   │   ├── saga-pattern-skill.md              # Compensating transactions
│   │   └── task-dependency-resolver-skill.md  # Kahn's algorithm, cycle detection
│   ├── artifacts-builder/     # Artifact generation patterns
│   ├── brand-guidelines/      # Brand consistency workflows
│   ├── canvas-design/         # Visual design in Canvas
│   ├── changelog-generator/   # Automated changelog creation
│   ├── competitive-ads-extractor/ # Ad intelligence gathering
│   ├── content-research-writer/ # Research + writing workflows
│   ├── developer-growth-analysis/ # Dev metrics analysis
│   ├── document-skills/       # Documentation automation
│   ├── domain-name-brainstormer/ # Domain naming ideation
│   ├── fastapi/               # FastAPI development patterns
│   ├── file-organizer/        # File organization automation
│   ├── image-enhancer/        # Image processing workflows
│   ├── internal-comms/        # Internal communication templates
│   ├── invoice-organizer/     # Invoice management automation
│   ├── lead-research-assistant/ # Lead qualification workflows
│   ├── mcp-builder/           # MCP server development
│   ├── meeting-insights-analyzer/ # Meeting analysis
│   ├── pict-test-designer/    # Pairwise testing design
│   ├── prompt-engineering/    # Prompt optimization patterns
│   ├── raffle-winner-picker/  # Random selection workflows
│   ├── skill-creator/         # Skill generation template
│   ├── skill-share/           # Skill sharing workflows
│   ├── slack-gif-creator/     # Slack integration patterns
│   ├── software-architecture/ # Architecture templates
│   ├── template-skill/        # Minimal/Standard/Comprehensive templates
│   ├── theme-factory/         # 10 professional themes
│   ├── video-downloader/      # Video processing workflows
│   └── webapp-testing/        # Web application testing
│
├── templates/
│   ├── commands/              # Advanced orchestration command templates (NEW in v1.1)
│   │   └── orchestration/
│   │       ├── dag-executor.md                    # DAG workflow execution
│   │       ├── dynamic-orchestrator.md            # Auto-scaling agent pools
│   │       ├── fault-tolerant-orchestrator.md     # Resilient workflows
│   │       ├── observability-tracker.md           # Distributed tracing
│   │       ├── performance-optimizer.md           # Performance analysis
│   │       └── state-coordinator.md               # State management
│   ├── orchestration/         # Planning templates for multi-agent workflows
│   │   ├── MULTI_AGENT_PLAN.md
│   │   └── TASK_DECOMPOSITION.md
│   └── skills/                # Skill complexity templates
│       ├── minimal-skill-template.md
│       ├── standard-skill-template.md
│       └── comprehensive-skill-template.md
│
├── examples/                  # Working examples with performance metrics (NEW in v1.1)
│   └── orchestration/         # Advanced orchestration pattern demonstrations
│       ├── 01-large-scale-refactoring/         # 1,247 files, 6.5x faster, 30% cost savings
│       ├── 02-multi-environment-deployment/    # Saga pattern, 55% downtime reduction
│       ├── 03-parallel-research-synthesis/     # 15 agents, 17.8x speedup, zero conflicts
│       ├── 04-distributed-testing/             # 5,247 tests, 11.2x speedup, 55% cost savings
│       └── 05-complex-feature-implementation/  # All 6 patterns, 3.5x speedup, 57% cost savings
│
├── INTEGRATION/               # Content ingestion and quality validation
│   ├── incoming/              # New content drop zone
│   ├── processed/             # 30 successfully integrated skills
│   ├── failed/                # Files that failed validation
│   └── logs/                  # Integration audit trails
│
├── MAINTENANCE/               # Repository health monitoring
│   ├── reports/               # Research briefs and architectural proposals
│   └── todo/                  # Staleness reports and action items
│
├── CLAUDE.md                  # Project-specific AI agent instructions
├── DEVELOPMENT_PLAN.md        # Roadmap and backlog
└── README.md                  # This file

Key Directories Explained

.claude/commands/: Active production commands for your local Claude Code installation
docs/best-practices/: 13 comprehensive manuals covering all aspects of command/agent/skill development
commands-templates/: 21 production-tested command templates ready to copy and customize
agents-templates/: 10 specialized agent configurations (v2.0 with consolidated patterns)
skills/: 20 production-ready skills for immediate use with agents
skills-templates/: 31 skill templates for creating new capabilities
templates/: Orchestration planning templates and skill complexity templates
INTEGRATION/: Automated content ingestion system with quality validation
MAINTENANCE/: Repository health monitoring with staleness detection

🎯 Quick Start

For Developers

Create your first command in 3 steps:

Read the basics
```
cat 02-Individual-Command-Creation.md
```

Use a template

cp templates/commands/start-session.md .claude/commands/

Run your command
```
/start-session
```

For AI Coding Assistants

When generating commands or agents:

Load core context:

@01-Introduction-and-Core-Principles.md
@CLAUDE.md

Review specific guidance:
- Commands → @02-Individual-Command-Creation.md
- Agents → @03-Individual-Agent-Configuration.md
- Orchestration → @04-Multi-Agent-Orchestration.md
Follow the documented patterns and use provided templates

For Multi-Agent Orchestration (NEW)

Launch parallel development in 4 steps:

Describe your feature

I need to implement user authentication with multiple approaches
(OAuth, JWT, and session-based) to compare and select the best

Orchestrate the feature
```
/orchestrate-feature
```
Creates MULTI_AGENT_PLAN.md with tasks, dependencies, and agent assignments
Spawn agents in parallel
```
/spawn-agents
```
Instantiates specialized agents in isolated git worktrees

Monitor and integrate

/coordinate-workflow  # Real-time progress tracking
/quality-gate         # Multi-stage validation

Result: 3 parallel implementations completed in 2-3 hours vs. 8 hours sequential

Example workflow:

# Agent 1 (Architect): Designs API specification → 30 min
# Agent 2 (Builder):   Implements OAuth 2.0     → 90 min
# Agent 3 (Builder):   Implements JWT           → 75 min
# Agent 4 (Validator): Security testing         → 45 min (waits for 2&3)

# Total wall-clock time: ~2.5 hours (vs 4+ hours sequential)
# Productivity gain: 3.2x faster + quality through comparison

📖 Documentation Structure

Core Instruction Manuals

Document	Purpose	Key Topics
01-Introduction-and-Core-Principles	Foundational philosophy and architecture	Agent-first design, core tenets, ecosystem architecture, success factors
02-Individual-Command-Creation	Technical specifications for slash commands	Command structure, naming, security, versioning, examples
03-Individual-Agent-Configuration	Agent setup and configuration	Role specialization, permissions, context management, memory
04-Multi-Agent-Orchestration	Coordinating multiple agents	Orchestrator-worker pattern, communication protocols, task decomposition
05-Testing-and-Quality-Assurance	Validation strategies	Testing approaches, static analysis, audit routines
06-Production-Deployment-and-Maintenance	Operations and monitoring	Deployment strategies, observability, rollback, lifecycle management
07-Quick-Reference-and-Templates	Boilerplate and cheat sheets	Command templates, agent configs, QA checklists, memory snippets
08-Claude-Skills-Guide	Skills creation and integration	Skill architecture, triggers, examples, orchestration patterns, best practices
09-Agent-Skills-vs-Multi-Agent	Strategic guidance on architecture	Skills-first approach, hybrid patterns, migration strategies, decision matrices
12-Skills-First-Planning-and-Orchestration	Planning for skills-first and multi-agent workflows	Decision framework, agent registries, multi-agent plans, orchestration patterns, metrics
15-Advanced-Orchestration-Patterns	Enterprise-grade orchestration patterns	DAG execution, state management, resilience, performance optimization, CRDT, saga pattern, circuit breakers

Reference Documentation

Document	Purpose	Source
Agent Skills Specification	Official format spec for SKILL.md files	Anthropic (agentskills.io)
Agent Skills Overview	What are skills? Concept introduction	Anthropic (agentskills.io)
Agent Skills Integration Guide	How to build skills-compatible agents	Anthropic (agentskills.io)

📚 Learning Paths

Choose your path based on your role and goals:

🎯 Path 1: Quick Start (30 minutes)

Goal: Get productive immediately with commands and skills

⚡ Command Quick Reference (5 min)
- Bookmark this page for daily reference
- Try: /start-session, /test-all, /pr
🎨 End-to-End Skill Creation (15 min)
- Generate your first skill from existing docs
- Understand the 4-step pipeline
🧠 Skills-First Paradigm (10 min)
- Learn why skills > multi-agent for most tasks
- See token efficiency gains (35% savings)

Next steps: Start using skills in your daily workflow, explore skill templates

👨‍💻 Path 2: Developer Onboarding (2 hours)

Goal: Master commands, agents, and skills for production use

Foundation (30 min)
- 📖 01-Introduction - Core philosophy
- 🎯 Quick Start - Essential workflows
Skills Mastery (45 min)
- 🧠 Skills-First Paradigm - Why and when
- 📘 08-Claude-Skills-Guide - Deep dive
- 🎨 End-to-End Skill Creation - Hands-on
Commands & Agents (30 min)
- 📝 02-Command-Creation - Build custom commands
- ⚙️ 03-Agent-Configuration - Configure agents
- ⚡ Command Quick Reference - Daily reference
Production Ready (15 min)
- ✅ 05-Testing-QA - Quality gates
- 🚀 06-Deployment - Deploy safely

Next steps: Contribute a skill, set up your team's workflow

🏗️ Path 3: Architecture & Planning (3 hours)

Goal: Design complex multi-agent systems and understand tradeoffs

Strategic Foundation (1 hour)
- 📖 01-Introduction - Philosophy
- 🧠 Skills-First Paradigm - Primary approach
- 📊 09-Skills-vs-Multi-Agent - Decision framework
Multi-Agent Patterns (1 hour)
- 🔀 04-Multi-Agent-Orchestration - Coordination
- 🌳 Git Worktrees + Multi-Agent - Parallel isolation
- 📋 12-Skills-First-Planning - Planning strategies
Implementation (45 min)
- 📝 02-Command-Creation - Orchestration commands
- ⚙️ 03-Agent-Configuration - Orchestrator agents
- 🎨 Skill Creation - Orchestration skills
Production & Metrics (15 min)
- ✅ 05-Testing-QA - Multi-agent testing
- 🚀 06-Deployment - Monitoring

Next steps: Design your first multi-agent workflow, measure productivity gains

🔧 Path 4: Skills Builder (1.5 hours)

Goal: Become a skill creation expert and build reusable capabilities

Skills Fundamentals (30 min)
- 🧠 Skills-First Paradigm - Core concepts
- 📘 08-Claude-Skills-Guide - Comprehensive guide
- 📖 Agent Skills Specification - Official format
Hands-On Creation (45 min)
- 🎨 End-to-End Skill Creation - Full pipeline
- 🛠️ Practice: Extract skill from your project docs
- 🛠️ Practice: Convert an existing agent to a skill
- 🛠️ Practice: Create skill from GitHub repo
Advanced Patterns (15 min)
- 🔄 Skill Orchestration - Compose skills
- 🎯 Pre-Built Skills - Learn from examples
- 📋 12-Skills-First-Planning - Planning with skills

Next steps: Build 3+ skills, contribute via /sharing-skills, measure adoption

🎯 Path 5: Problem-Specific Guides

Choose based on what you need to accomplish:

Need to: Create a command

Need to: Build a skill

Need to: Setup multi-agent workflow

Need to: Improve quality & testing

✅ 05-Testing-and-Quality-Assurance
⚡ Command Quick Reference

Need to: Deploy to production

🚀 06-Production-Deployment-and-Maintenance
🔒 Security & Safety

Need to: Quick answers

⚡ Command Quick Reference
📋 07-Quick-Reference

📊 Path 6: Team Lead / Manager (1 hour)

Goal: Understand ROI, adoption strategy, and team efficiency gains

Business Case (15 min)
- 📊 Success Metrics - 28.4% cost reduction, 40% faster delivery
- 🧠 Skills-First Paradigm - 35% token savings
- 🌳 Git Worktrees Pattern - 3-10x speed gains
Strategic Guidance (20 min)
- 📖 01-Introduction - Philosophy
- 📊 09-Skills-vs-Multi-Agent - Architecture decisions
- 📋 12-Skills-First-Planning - Planning approach
Adoption Plan (15 min)
- 👨‍💻 Review "Path 2: Developer Onboarding" (assign to team)
- 🔧 Review "Path 4: Skills Builder" (assign to senior devs)
- ⚡ Command Quick Reference (bookmark for team)
Quality & Operations (10 min)
- ✅ 05-Testing-QA - Standards
- 🚀 06-Deployment - Production readiness
- 🔒 Security & Safety - Risk mitigation

Next steps: Pilot with 2-3 developers, measure metrics, scale adoption

🎓 Recommended Reading Order by Experience Level

Beginner (Never used AI agents):

Quick Start Path (30 min)
Read 01-Introduction (20 min)
Try /start-session, /test-all, /pr commands
Create first skill from your docs
Total: 1 hour to productivity

Intermediate (Used Claude/ChatGPT for coding):

Skills-First Paradigm (15 min) - understand efficiency gains
Developer Onboarding Path (2 hours) - comprehensive mastery
Try multi-agent with git worktrees (hands-on)
Build 2-3 custom skills
Total: 4 hours to expert-level productivity

Advanced (Built AI agents before):

Architecture & Planning Path (3 hours) - strategic depth
Compare your patterns to skills-first approach
Review decision frameworks and migration strategies
Design complex orchestration workflows
Contribute patterns back to community
Total: 6 hours to architectural mastery

🎨 Template Library

Agent Templates

Professional agent configurations for specialized roles.

Note: With Anthropic's skills-first approach, these templates now serve two purposes:

As Skill Packages (Recommended): Convert to skills for use with a general agent
- More efficient and maintainable
- Can be composed with other skills
- See Phase 4 conversions in progress
As Multi-Agent Configs (For Parallel Work): Use when spawning workers for concurrent tasks
- Each worker loads appropriate skills
- Use orchestrator-worker pattern
- See Multi-Agent Orchestration guide

Migration Path: Most users should start by using these as skills with a general agent, and only introduce multi-agent orchestration when parallel execution is necessary.

Agent	Purpose	Key Capabilities
Architect	System design and planning	Architecture assessment, planning document creation, design decisions
Builder	Code implementation	Feature development, TDD implementation, git workflow management
Validator	Testing and code review	Test creation, code review, coverage validation, security audits
Scribe	Documentation	API docs, deployment guides, architecture documentation
DevOps	Infrastructure and deployment	CI/CD pipelines, infrastructure as code, monitoring setup
Researcher	Technical research	Technology evaluation, competitive analysis, feasibility studies
Integration Manager	Content ingestion and integration	File categorization, quality validation, documentation updates, audit trails

Orchestration Agent Templates

Multi-agent coordination and parallel execution specialists:

Agent	Model	Purpose	Key Capabilities
Orchestrator Lead	Claude Opus 4	Multi-agent workflow coordination	Request decomposition, agent spawning, result synthesis, quality control
Task Coordinator	Claude Sonnet 4	Dependency and resource management	Dependency graphs, parallel optimization, bottleneck detection, resource balancing
Integration Orchestrator	Claude Sonnet 4	Result merging and validation	Cross-agent merging, conflict resolution, git worktree integration, final validation
Monitoring Agent	Claude Haiku 3.5	Real-time tracking and metrics	Execution tracking, performance metrics, error detection, cost monitoring

Command Templates

Core Workflow Commands

start-session.md - Initialize development session with context loading
close-session.md - Gracefully end session with progress summary
plan.md - Generate or update project plans
summarize.md - Summarize recent work and changes
pr.md - Streamline pull request creation
handoff.md - Create comprehensive work handoff documents

Quality Assurance Commands

test-all.md - Execute comprehensive test suites
lint-fixes.md - Auto-fix code style issues
error-report.md - Diagnose and report errors
deps-update.md - Audit and update dependencies

Utility Commands

docs.md - Generate project documentation
search.md - Search codebase with context
cleanup.md - Maintain workspace health
env-check.md - Validate development environment

Integration & Maintenance Commands

create-skill.md - Generate Claude AI skills from documentation, GitHub repos, or PDFs using Skill Seekers
integration-scan.md - Scan and categorize files in /INTEGRATION/incoming directory
maintenance-scan.md - Identify stale files (>30 days) and generate maintenance reports

Multi-Agent Orchestration Commands

Advanced parallel development and coordination:

orchestrate-feature.md - Multi-agent feature development with parallel task execution and git worktree isolation
spawn-agents.md - Dynamic agent instantiation with role assignment, context isolation, and resource allocation
coordinate-workflow.md - Real-time inter-agent communication, result aggregation, and conflict resolution
worktree-setup.md - Automated git worktree lifecycle management with branch strategy enforcement
quality-gate.md - Multi-stage validation pipeline with parallel test execution and security audits

Orchestration Planning Templates

Essential planning documents for skills-first and multi-agent workflows:

Template	Purpose	Use When
AGENT_REGISTRY.md	Track agent capabilities and skill compatibility	Setting up orchestration projects, documenting available agents
MULTIAGENT_PLAN.md	Structured multi-agent planning with skills composition	Planning parallel development, coordinating multiple agents

See Also: 12-Skills-First-Planning-and-Orchestration for comprehensive planning guidance

🎯 Claude Skills

NEW: Extend command and agent capabilities with reusable workflow automation.

What Are Skills?

Skills are portable workflow automation units that complement commands and agents:

Commands: Quick session shortcuts (/test, /pr)
Agents: Role-specialized project execution (Builder, Validator)
Skills: Cross-project reusable workflows (PR review, code formatting, doc generation)

Getting Started with Skills

Step 1: Identify a workflow that repeats ≥3x per week

Step 2: Use the skill creator:

"Use skill-creator skill to help me build a skill for [your workflow]"

Step 3: Choose your template:

Simple workflows → templates/skills/minimal-skill-template.md
Moderate workflows → templates/skills/standard-skill-template.md
Complex workflows → templates/skills/comprehensive-skill-template.md

Step 4: Test and deploy

🎨 End-to-End Skill Creation Workflow

Create production-ready Claude skills from any source in 4 automated steps.

This comprehensive guide walks through the complete skill creation pipeline, from identifying a source to deploying a validated, production-ready skill. Whether you're extracting patterns from documentation, GitHub repositories, or PDF manuals, this workflow ensures quality and consistency.

Why Create Skills?

✅ Benefits:

Portability: Share expertise across teams and projects
Consistency: Standardize workflows and best practices
Efficiency: Automate repetitive multi-step processes
Knowledge Capture: Preserve institutional knowledge as executable code
Rapid Onboarding: New team members inherit expert workflows immediately

✅ Create a skill when:

You've solved a complex problem that others will face
You have a multi-step workflow you repeat frequently
You want to standardize a process across your organization
You're integrating specialized domain knowledge into AI workflows
You need to ensure quality gates and validation steps

❌ Don't create a skill when:

The task is a one-time operation
The process is already well-handled by existing tools
The workflow is too simple (< 3 steps)
Requirements are still evolving rapidly

Overview: The 4-Step Pipeline

Source Material → Generate → Validate → Integrate → Production
   (Docs/GitHub/PDF)     ↓          ↓          ↓         ↓
                    SKILL.md   Quality    README    Ready to Use
                               Checks     Update

Timeline: 5-30 minutes depending on source complexity

The automated pipeline handles:

Content extraction from your source
Skill structure generation following best practices
Quality validation with 7-stage checks
Documentation integration into repository indices
Production deployment ready for immediate use

Step 1: Generate Skill from Source

Choose your source type and run the appropriate command:

Option A: From Documentation Files

Use when: You have markdown docs, text files, or local documentation

skill-seekers docs path/to/documentation/

Example:

# Generate skills from FastAPI documentation
skill-seekers docs ~/projects/fastapi-docs/

# Generate from multiple markdown files
skill-seekers docs ./guides/*.md

What happens:

Scans all .md, .txt, and documentation files
Extracts patterns, workflows, and best practices
Generates structured SKILL.md files
Places output in output/[source-name]/
Creates scan report with quality metrics

Option B: From GitHub Repository

Use when: You want to extract patterns from open-source projects

skill-seekers github owner/repo [--enhance]

Example:

# Basic: Extract from repository structure
skill-seekers github fastapi/fastapi

# Enhanced: Include README, docs, and code analysis
skill-seekers github fastapi/fastapi --enhance

Flags:

--enhance: Deep analysis including README, documentation files, and code patterns (recommended for comprehensive extraction)

What happens:

Clones repository (or uses cached version)
Analyzes project structure and patterns
With --enhance: Processes README.md and docs/ directory
Generates skill capturing project's best practices
Creates detailed extraction report

Option C: From PDF Manual

Use when: You have PDF documentation, whitepapers, or technical manuals

skill-seekers pdf path/to/manual.pdf

Example:

# Generate skill from technical manual
skill-seekers pdf ~/Downloads/kubernetes-best-practices.pdf

# Process multiple PDFs
skill-seekers pdf ./manuals/*.pdf

What happens:

Extracts text content from PDF
Preserves structure (headings, lists, code blocks)
Identifies workflows and procedures
Generates skill with preserved formatting
Creates extraction quality report

Step 2: Review Scan Report

After generation completes, you'll find:

Generated skills: output/[source-name]/SKILL.md
Scan report: output/[source-name]/scan_report.md
Metadata: Quality scores, extraction statistics

Why this matters: The scan report helps you understand what was extracted and identify potential quality issues before validation.

What to verify:

✅ Completeness: All key workflows captured
✅ Structure: Proper frontmatter, sections, examples
✅ Accuracy: Technical details preserved correctly
✅ Clarity: Instructions are clear and actionable
✅ Dependencies: External tools/libraries documented
✅ Edge cases: Error handling and troubleshooting included

Common issues and fixes:

Issue	Symptom	Fix
Incomplete extraction	Missing workflows or sections	Re-run with `--enhance` flag (GitHub) or include more source files
Formatting errors	Broken markdown, invalid YAML	Manually edit `SKILL.md` before validation
Too generic	Lacks specific examples or details	Add concrete examples in `## Examples` section
Missing context	Unclear when/why to use skill	Enhance `## Purpose` and `## Use When` sections
No error handling	Doesn't address failure scenarios	Add `## Troubleshooting` section
Outdated patterns	Source material is old	Update skill with current best practices

Step 3: Validate & Process

Move generated skills into the integration pipeline for automated validation:

# Copy generated skill to incoming directory
cp output/fastapi/SKILL.md INTEGRATION/incoming/fastapi-skill.md

# Run integration scan
/integration-scan

# Review validation results
cat INTEGRATION/logs/scan-report-[timestamp].md

The 7-stage validation pipeline checks:

File Structure ✓
- Valid frontmatter YAML
- Required fields present (name, description, version)
- Proper markdown formatting
Content Quality ✓
- Purpose section clearly explains intent
- Usage examples provided
- Error handling documented
- Minimum content length met
Category Assignment ✓
- Automatically categorized as Skill
- Subcategory identified from content analysis
- Proper directory structure determined
Naming Conventions ✓
- Follows kebab-case naming
- No special characters or spaces
- Descriptive and action-oriented
Cross-References ✓
- Links to existing files are valid
- No broken references
- Dependencies properly documented
Security Scan ✓
- No hardcoded credentials
- No suspicious command execution patterns
- Path traversal vulnerabilities checked
Best Practices ✓
- Follows skill template structure
- Includes versioning
- Has clear success criteria

After successful validation:

✅ Skill moved to INTEGRATION/processed/[skill-name]/
✅ Quality score assigned (0-100)
✅ Ready for documentation integration

If validation fails:

⚠️ Skill moved to INTEGRATION/failed/
⚠️ Detailed error report generated
⚠️ Fix issues and re-run /integration-scan

Step 4: Update Documentation

Once validated, integrate the skill into repository documentation:

# Run integration update command
/integration-update-docs

# Or manually update using documentation-update skill
# This skill knows how to update all indices and catalogs

What gets updated:

README.md Skills Catalog
- New row added to Pre-Built Skills table
- Skill name, purpose, and use-when description
- Alphabetically sorted for easy discovery

Skills Registry (skills/registry.json)

{
  "fastapi": {
    "name": "FastAPI Development Patterns",
    "version": "1.0.0",
    "category": "backend",
    "path": "skills-templates/fastapi/",
    "quality_score": 95
  }
}

Template Indices
- skills-templates/README.md updated
- Cross-references added to related templates
- Integration examples provided
Integration Logs
- Timestamped audit trail in INTEGRATION/logs/
- Tracks who added what, when, and validation scores
- Enables quality trend analysis over time

Result: Production-Ready Skill

Your skill is now ready for use in 5 different ways:

1. Via Skill Tool (Recommended)

Uses the Skill tool with skill="fastapi"

2. Via Slash Command

# If you created a wrapper command
/fastapi

3. Via Agent Configuration

# In .claude/agents/backend-builder.md
context:
  skills:
    - fastapi
    - testing
    - deployment

4. Via Direct File Reference

Follow the workflow in skills-templates/fastapi/SKILL.md

5. Via Skill Orchestrator

Uses the skill-orchestrator to coordinate fastapi, database-design, and api-testing skills

Timeline Reference

Source Type	Generation	Review	Validation	Documentation	Total
Small docs (< 10 files)	2 min	3 min	1 min	1 min	~7 min
Medium docs (10-50 files)	5 min	5 min	2 min	1 min	~13 min
Large docs (> 50 files)	10 min	10 min	3 min	2 min	~25 min
GitHub basic	3 min	5 min	1 min	1 min	~10 min
GitHub enhanced	8 min	10 min	2 min	1 min	~21 min
PDF simple (< 50 pages)	4 min	5 min	1 min	1 min	~11 min
PDF complex (> 50 pages)	10 min	15 min	2 min	2 min	~29 min

Actual times vary based on source complexity, network speed, and system performance.

Troubleshooting Common Issues

Issue: skill-seekers command not found

# Solution: Install or update skill-seekers
pip install -e skills-templates/skill-creator/scripts/
# Or use the full path
python3 skills-templates/skill-creator/scripts/skill_seekers.py docs ./

Issue: Generation produces empty or minimal skill

# Solution: Check source content quality
# - Ensure source has clear workflows and patterns
# - Try --enhance flag for GitHub repositories
# - Provide more comprehensive source material

Issue: Validation fails with "Missing required fields"

# Solution: Manually add frontmatter
# Edit SKILL.md and ensure it starts with:
---
name: your-skill-name
description: Clear one-line description
version: 1.0.0
---

Issue: Skill works but quality score is low

# Solution: Enhance the skill content
# - Add more detailed examples in ## Examples section
# - Include troubleshooting guidance
# - Document dependencies and prerequisites
# - Add success criteria and validation steps

Issue: Documentation update doesn't reflect new skill

# Solution: Manually trigger documentation update
/integration-update-docs
# Or use the documentation-update skill directly

Issue: Generated skill is too generic

# Solution: Use more specific source material
# - Include code examples in source docs
# - Add real-world use cases
# - Document edge cases and gotchas
# - Provide context about when/why to use patterns

Pre-Built Skills

Skill	Purpose	Use When
agent-skill-bridge	Integrates agents and skills	Coordinating agents with skills
agent-communication-protocol	Open protocol for AI agent interoperability	Multi-agent communication, framework-agnostic agents, REST API
ar-io-build	Comprehensive AR.IO build documentation	Building with AR.IO, implementing AR.IO solutions, debugging AR.IO code
arweave-ao-cookbook	Build decentralized applications on AO	Building decentralized apps on Arweave with permanent storage
arweave-standards	Arweave standards, specifications and best practices	Working with Arweave standards, implementing protocol specifications, checking compliance
artifacts-builder	React/Tailwind/shadcn UI artifact builder	Complex artifacts requiring state management or shadcn/ui components
astro	Astro web framework with Islands architecture	Content-focused websites, partial hydration, content collections, multi-framework support
braiins-ecosystem	Unified Braiins Bitcoin mining ecosystem	Complete mining stack (firmware, pool, tools, proxy, dashboard, calculator)
braiins-insights	Bitcoin mining profitability calculator	Evaluating mining profitability, ROI analysis, cash flow projections
braiins-manager	Web-based mining operations dashboard	Fleet monitoring, multi-user access, real-time metrics
braiins-os	ASIC firmware with autotuning	Firmware management, API integration, OS feeds
braiins-pool	Bitcoin mining pool (FPPS, Lightning)	Mining pool setup, FPPS rewards, Lightning payouts, Stratum V2
braiins-proxy	Stratum V2 mining proxy	Large-scale operations, hashrate aggregation, farm proxy
braiins-toolbox	Batch mining operations management	Network scanning, firmware/system/miner management, performance tuning
brand-guidelines	Anthropic brand colors and typography	Applying brand standards to artifacts
canvas-design	Visual art creation using design philosophy	Creating posters, art, or static visual pieces
changelog-generator	Git commits to user-friendly changelogs	Preparing release notes or product updates
chezmoi	Dotfiles manager with 56 commands, templates, password managers, encryption	Cross-machine dotfiles, machine-specific configs, encrypted secrets
claude-mem	Persistent memory compression system for Claude Code	Cross-session context, MCP search, privacy controls, observations
cloudflare-ai-gateway	Unified interface to AI providers (OpenAI, Anthropic, Azure, HuggingFace)	Multi-provider AI proxy, caching, rate limiting, analytics
cloudflare-ai-search	Semantic search and vector embeddings in Workers	Vector-based search, embedding models
cloudflare-kv	Low-latency key-value storage at the edge	Edge storage, get/put/delete/list operations
cloudflare-pages	JAMstack platform for static sites + serverless functions	13 framework guides, Pages Functions, static hosting
cloudflare-pulumi	Infrastructure as Code for Cloudflare resources	Multi-language IaC (TypeScript, Python, Go)
cloudflare-r2	S3-compatible object storage with zero egress fees	S3 API, bucket management, data access
cloudflare-workers	Serverless edge computing with V8 runtime	Runtime APIs, fetch handlers, Durable Objects, KV bindings
cloudflare-zaraz	Server-side tag management with edge execution	Web API, consent management, GTM migration, 34+ tools
cloudflare-web-analytics	Privacy-first web analytics with Core Web Vitals	Free analytics, SPA tracking, RUM beacon, no cookies
coinmarketcap-api	Enterprise-grade cryptocurrency market data API	Crypto prices, market caps, exchanges, historical data, 40+ endpoints
competitive-ads-extractor	Analyze competitors' ads from ad libraries	Understanding competitor messaging and creative approaches
conductor	Build and deployment orchestration	Working with conductor, implementing conductor solutions, debugging conductor code
content-research-writer	Writing assistance with research and citations	Writing articles, documentation, blog posts
create-llmstxt-py	Python script generating llms.txt files using Firecrawl and OpenAI	Making websites LLM-accessible, automated content indexing, documentation extraction
developer-growth-analysis	Coding pattern analysis from Claude Code history	Identifying development gaps and curating learning resources
docling	IBM Research document processing library for AI	Parsing PDFs/DOCX, extracting tables/layouts, building RAG pipelines, MCP server for documents
document-skills/docx	Word document creation and editing	Working with .docx files, tracked changes, or comments
dokploy	Comprehensive assistance with dokploy	Deploying Docker applications with Dokploy platform
dokploy-mcp	AI-driven deployment management using Dokploy MCP server	Deploying apps, provisioning databases, managing Dokploy infrastructure
dnsdist	DNS load balancer with DoS protection and multi-protocol support	Load balancing DNS, DoH/DoT/DoQ, rate limiting, dynamic blocking
document-skills/pdf	PDF manipulation toolkit	Extracting text, creating PDFs, or filling PDF forms
document-skills/pptx	PowerPoint presentation toolkit	Creating or editing presentations
document-skills/xlsx	Excel spreadsheet toolkit	Working with spreadsheets, formulas, or data analysis
documentation-update	Update repository documentation tables and indices	Adding entries to README, maintaining indices
domain-name-brainstormer	Domain name generation and availability checking	Finding available domain names for projects
farm-monitor	Bitcoin mining fleet monitoring	Monitoring mining operations, fleet management
fastapi	FastAPI modern Python web framework	Building APIs, async endpoints, dependency injection, Python backend development
fastmcp	Model Context Protocol (MCP) server development with FastMCP framework	Creating MCP servers, Claude Desktop integration, building AI tools/resources, production MCP deployment (Python + TypeScript)
file-categorization	Categorize files as Command/Agent/Skill/Doc	Processing files in integration pipelines
file-organizer	Intelligent file organization	Organizing files, finding duplicates, or cleaning up directories
flyio	Deploy and scale full-stack applications globally on Fly.io platform	When deploying web applications, APIs, databases, or microservices that need global distribution and automatic scaling
github-copilot	AI coding assistant with suggestions, chat, code review	Using GitHub Copilot features, IDE integration, custom instructions
github-pages	GitHub Pages static site hosting	Creating sites, custom domains, Jekyll themes, GitHub Actions deployment
gitbook	GitBook documentation platform	Spaces, Git sync, custom domains, OpenAPI, change requests
google-seo	Google SEO best practices and web optimization	Creating web content, reviewing pages for SEO, implementing metadata, structuring URLs and site architecture
google-structured-data	Schema.org markup for Google Search rich results	JSON-LD templates, Article/Product/Event/FAQ markup, JavaScript generation
google-seo-starter-guide	Google SEO fundamentals and best practices	Implementing SEO for new sites, optimizing URLs and content, improving search visibility, auditing SEO implementation
google-url-inspection	Search Console URL Inspection Tool guide	Verifying indexing status, diagnosing crawl issues, requesting re-indexing, troubleshooting rendering problems
image-enhancer	Image quality improvement	Enhancing screenshots or images for presentations
internal-comms	Internal communications templates	Writing status reports, newsletters, or company updates
invoice-organizer	Invoice and receipt organization	Tax preparation or bookkeeping
just	Just command runner for project task automation	Creating justfile recipes, replacing Make/shell scripts, cross-platform command execution
langflow	Visual AI workflow platform with MCP integration	Building AI agent workflows visually, integrating MCP servers, deploying production AI agents
latex-manual	Comprehensive LaTeX reference with templates and troubleshooting	Writing LaTeX documents, creating equations, formatting papers, making presentations, debugging compilation
latex-wikibook	Comprehensive LaTeX tutorials from WikiBooks	Learning LaTeX best practices, LaTeX formatting, document preparation
lead-research-assistant	Lead identification and qualification	Sales, business development, or marketing research
mailgun	Email sending, receiving, and tracking API	Working with Mailgun, implementing email solutions, debugging email code
mcp-builder	MCP server development guide	Building Model Context Protocol servers
mcp-registry	MCP server discovery and publishing registry	Publishing MCP servers, server discovery, authentication
meeting-insights-analyzer	Meeting transcript analysis	Improving communication or leadership skills
neon	Neon serverless Postgres with branching	Serverless database, autoscaling, scale-to-zero, pgvector, edge-compatible drivers
openserv-agents	OpenServ platform for AI agents (SDK, API, no-code)	Building autonomous agents, "Second Brain" architecture, BRAID framework, multi-agent orchestration, deployment guides
openrouter	Unified API gateway for 100+ AI models	Working with OpenRouter, multi-provider routing, cost optimization, model comparison
passwordless-docs	Bitwarden Passwordless.dev documentation, SDKs, and React examples	Implementing passwordless authentication, integrating FIDO2/WebAuthn, building React passwordless auth
pict-test-designer	PICT pairwise test case design	Designing comprehensive test cases with minimal coverage
powerdns-authoritative	PowerDNS authoritative nameserver with DNSSEC, REST API, multiple backends	Authoritative DNS setup, zone management, dynamic DNS, Lua records
powerdns-recursor	High-performance recursive DNS resolver with DNSSEC validation and Lua scripting	Recursive DNS, RPZ, Lua hooks, DNSSEC validation
prompt-engineering	Advanced prompt engineering patterns	Writing commands, hooks, skills, or optimizing LLM interactions
quiche	Cloudflare QUIC/HTTP3 Rust library	QUIC connections, HTTP/3 clients/servers, connection management
raffle-winner-picker	Random winner selection	Running giveaways, raffles, or contests
raycast	Raycast extension development framework	Building Raycast extensions with TypeScript/React, API integration (Environment, Clipboard, Storage, OAuth), UI components (List, ActionPanel, Form)
root-cause-tracing	Systematic debugging through call stack	Tracing bugs deep in execution
sdk-sm	Bitwarden Secrets Manager SDK	Using Bitwarden Secrets Manager, working with multi-language SDK (Rust, Python, C#, Go, Java), secrets management API
seo	Google SEO research and web traffic monetization	SEO best practices, tool comparisons (Semrush, Moz, Ahrefs), search engine optimization, marketing
sharing-skills	Contribute skills upstream via PR	Sharing broadly useful patterns
skill-creator	Guide for creating effective skills	Building new skills with specialized knowledge
skill-orchestrator	Coordinates multiple skills	Complex multi-skill workflows
skill-share	Skill creation and Slack sharing	Automating skill sharing with teams
slack-gif-creator	Animated GIF creation for Slack	Creating GIFs optimized for Slack constraints
software-architecture	Clean Architecture & DDD guidance	Software design, code quality, anti-patterns
subagent-driven-development	Execute plans with fresh subagents per task	Plan execution with quality gates
theme-factory	10 pre-set themes for artifact styling	Applying professional themes to slides, docs, or HTML
terraform	HashiCorp Terraform Infrastructure as Code (IaC)	Managing cloud infrastructure, writing .tf files, state management, multi-cloud provisioning
turbo-python-sdk	Python SDK for Ardrive Turbo Upload and Payment Service	Arweave uploads with Python, companion to turbo-sdk
turbo-sdk	Complete Arweave Turbo ecosystem including client SDKs, core upload infrastructure, payment service backend, and CLI tools	Arweave uploads, permanent storage, ANS-104 bundling, multi-signature support, AWS-scale infrastructure
twilio-voice	Comprehensive Twilio Voice API assistance with AI integration patterns	Voice assistants, OpenAI Realtime API, function-calling agents, Conversational Intelligence
ui-ux-pro-max	UI/UX design intelligence with 50+ styles, color palettes, font pairings, and 8 framework stacks	Frontend design, component styling, accessibility
using-git-worktrees	Isolated workspace management	Feature work needing isolation
using-superpowers	Meta-skill for skill discovery	Starting any conversation, ensuring skill usage
venice-ai	Privacy-focused AI platform assistance	Working with Venice.ai, privacy-focused AI implementations, platform features
video-downloader	Video downloads from YouTube and platforms	Downloading videos for offline viewing or archival
wao	Wizard AO SDK & Testing framework	Working with WAO SDK, testing AO applications, understanding AO development
weavedb	Decentralized database protocol with zero-knowledge proofs	Building with WeaveDB, implementing decentralized databases, permanent storage solutions
x402	HTTP 402 payment protocol for crypto-native API monetization	Implementing paid APIs, AI agent payments, micropayments, USDC integration, MCP server payments
webapp-testing	Playwright-based web app testing	Testing local web applications or debugging UI

Orchestration Skills (NEW)

Advanced Orchestration Skills - Enterprise-grade patterns (Document 15):

Skill	Purpose	Use When
task-dependency-resolver-skill	Kahn's algorithm for topological sorting and cycle detection	Executing workflows with complex task dependencies (DAG execution)
agent-pool-manager-skill	Auto-scaling, health monitoring, and agent recycling	Managing variable workloads with dynamic agent pools
distributed-state-sync-skill	CRDT implementations for conflict-free distributed state	Sharing state across concurrent agents with automatic conflict resolution
saga-pattern-skill	Compensating transactions for distributed workflows	Multi-step workflows requiring automatic rollback on failure
circuit-breaker-skill	3-state FSM to prevent cascading failures	Protecting against failing external services or dependencies
performance-profiler-skill	Token usage analysis and bottleneck detection	Optimizing costs and meeting performance SLAs

Basic Orchestration Skills - Multi-agent coordination:

Skill	Purpose	Use When
multi-agent-planner-skill	Automated MULTI_AGENT_PLAN.md generation	Creating multi-agent plans for complex features
parallel-executor-skill	Concurrent task execution orchestration	Executing tasks in parallel across agents
worktree-manager-skill	Git worktree lifecycle management	Setting up isolated workspaces for agents
agent-communication-skill	Inter-agent messaging and handoffs	Facilitating communication between agents

Resources

Documentation: docs/best-practices/08-Claude-Skills-Guide.md
Templates: templates/skills/
Examples: skills/*/SKILL.md
Best Practices: See comprehensive skills guide
Official Spec: docs/references/agent-skills-specification.md (Anthropic's open standard)

🧠 The Skills-First Paradigm

Anthropic's latest research reveals a fundamental shift: For most AI workflows, a single general agent dynamically loading skills dramatically outperforms multiple specialized agents in cost, efficiency, and maintainability.

Why Skills Win: The Research

Token Efficiency: Skills-first achieves 35% reduction in token usage vs. multi-agent

Root cause: Context sharing and progressive disclosure
Multi-agent: Each agent loads full context independently (15x baseline)
Skills-first: Single agent loads base context once, then adds skills progressively (5-7x baseline)

Maintenance Burden: One agent configuration vs. N agent definitions

Multi-agent: Update N agents when patterns evolve
Skills-first: Update 1 agent + M skills (where M is typically smaller than N)
Real savings: 60-80% reduction in configuration maintenance

Context Continuity: No context loss between steps

Multi-agent: Handoffs require serializing context, losing nuance
Skills-first: Same agent maintains full context from start to finish
Quality impact: Fewer misunderstandings, better coherence

The Paradigm Shift

OLD Approach (Multi-Agent Specialization):

# Separate agent for each capability
agents:
  - oauth-agent.md         # Handles OAuth only
  - jwt-agent.md           # Handles JWT only
  - session-agent.md       # Handles sessions only
  - validation-agent.md    # Handles validation only

workflow:
  1. OAuth agent authenticates → hands off to JWT agent
  2. JWT agent issues token → hands off to Session agent
  3. Session agent creates session → hands off to Validation agent
  4. Validation agent verifies → returns to orchestrator

problems:
  - 4 agent configs to maintain
  - 3 handoff points (context loss risk)
  - Each agent loads independent context
  - 15x token usage vs. baseline

NEW Approach (Skills-First with Single Agent):

# General agent loads capabilities on demand
agent: general-backend-agent.md

skills:
  - oauth-skill.md
  - jwt-skill.md
  - session-skill.md
  - validation-skill.md

workflow:
  1. Agent loads oauth-skill → authenticates
  2. Agent loads jwt-skill → issues token
  3. Agent loads session-skill → creates session
  4. Agent loads validation-skill → verifies
  5. All in same context, zero handoffs

benefits:
  - 1 agent config + 4 skills
  - 0 handoff points
  - Progressive context loading
  - 5-7x token usage vs. baseline (65% savings)
  - Skills reusable across projects

Real-World Examples

Example 1: Bug Fix Workflow

❌ Multi-Agent Approach (Inefficient):

User: "Fix the login timeout bug"

1. Orchestrator analyzes → spawns Debug-Agent
   (Context: Load project, analyze codebase - 10K tokens)

2. Debug-Agent investigates → hands off to Fix-Agent
   (Context: Re-load project, previous findings - 12K tokens)

3. Fix-Agent implements → hands off to Test-Agent
   (Context: Re-load project, understand fix - 11K tokens)

4. Test-Agent validates → reports back
   (Context: Re-load test suite, understand changes - 9K tokens)

Total: 42K tokens, 3 handoffs, context duplicated 4 times

✅ Skills-First Approach (Efficient):

User: "Fix the login timeout bug"

Single Agent workflow:
1. Loads root-cause-tracing-skill → identifies bug location
   (Context: Project loaded once - 10K tokens)

2. Loads builder-skill → implements fix
   (Additional context: Just the skill - +2K tokens)

3. Loads validator-skill → writes and runs tests
   (Additional context: Just the skill - +2K tokens)

Total: 14K tokens, 0 handoffs, context maintained throughout
Savings: 67% reduction in tokens, zero context loss

Example 2: Feature Implementation

Scenario: Add user profile picture upload

❌ Multi-Agent (6 agents, 8 handoffs):

workflow:
  - Architect-Agent: Design upload system → 15K tokens
  - Frontend-Agent: Build UI component → 18K tokens (reload context)
  - Backend-Agent: Create API endpoint → 17K tokens (reload context)
  - Storage-Agent: Configure S3 integration → 14K tokens (reload context)
  - Security-Agent: Add validation → 16K tokens (reload context)
  - Test-Agent: Write tests → 19K tokens (reload context)

total: 99K tokens across 6 agents
handoffs: 8 (context serialization overhead)
maintenance: 6 agent configs to keep in sync

✅ Skills-First (1 agent, 6 skills):

workflow:
  - Agent loads architect-skill: Design system → 15K tokens (initial)
  - Agent loads frontend-skill: Build UI → +3K tokens
  - Agent loads backend-skill: Create API → +3K tokens
  - Agent loads storage-skill: S3 setup → +2K tokens
  - Agent loads security-skill: Validation → +2K tokens
  - Agent loads testing-skill: Test suite → +3K tokens

total: 28K tokens with single agent
handoffs: 0 (same agent, continuous context)
maintenance: 1 agent + 6 reusable skills
savings: 72% token reduction, 100% context preservation

Example 3: Code Review

❌ Multi-Agent (Sequential specialists):

PR submitted → 4 specialized review agents

1. Style-Agent reviews formatting → 8K tokens
2. Security-Agent scans vulnerabilities → 9K tokens (reload code)
3. Performance-Agent checks efficiency → 10K tokens (reload code)
4. Logic-Agent validates correctness → 11K tokens (reload code)

Total: 38K tokens, each agent reprocesses same code
Result: 4 separate reports requiring manual synthesis

✅ Skills-First (Comprehensive single pass):

PR submitted → General agent with review skills

1. Agent loads code-review-skill
   - Checks style
   - Scans security
   - Analyzes performance
   - Validates logic
   - Generates unified report

Total: 12K tokens, code loaded once
Result: Single coherent report with cross-cutting insights
Savings: 68% tokens + better analysis (sees interactions)

Decision Framework: When to Use What

Task Type	Dependencies	Recommended Approach	Why
Bug fix	Sequential	✅ Single agent + skills	Context continuity critical for understanding cause → fix → test flow
Small feature (< 500 LOC)	Sequential	✅ Single agent + skills	Overhead of multi-agent exceeds benefits
Large feature (> 500 LOC)	Mixed	✅ Single agent + skills OR Hybrid	Skills-first unless parallel workstreams needed
Research task	Independent	✅ Multi-agent	Breadth-first exploration benefits from parallel investigation
Code review	Sequential	✅ Single agent + skills	Cross-cutting analysis requires unified context
Refactoring	Sequential	✅ Single agent + skills	Must maintain coherent mental model across changes
Documentation	Sequential	✅ Single agent + skills	Narrative flow requires continuous context
Testing	Can parallelize	⚖️ Skills OR Multi-agent	Skills for sequential, multi-agent if test suites are truly independent
Deployment	Parallel environments	✅ Multi-agent	Deploy to dev/staging/prod simultaneously
POC exploration	Independent	✅ Multi-agent	Compare multiple approaches in parallel
Migration	Sequential	✅ Single agent + skills	State transitions must be coordinated
Performance optimization	Sequential	✅ Single agent + skills	Requires holistic view of system interactions

Detailed Decision Criteria

✅ Use Single Agent + Skills When:

Context Matters - The task requires understanding accumulated context from previous steps
- Example: Refactoring where later changes depend on earlier architectural decisions
- Why skills win: Zero context loss, agent maintains full understanding
Sequential Dependencies - Step B cannot start until Step A completes
- Example: Design API → Implement endpoints → Write tests → Document
- Why skills win: Natural workflow, no handoff overhead
Cross-Cutting Analysis - Need to see interactions and relationships
- Example: Security review examining how auth, data validation, and logging interact
- Why skills win: Unified view enables spotting subtle vulnerabilities
Iterative Refinement - Task involves back-and-forth adjustments
- Example: UI development with continuous styling tweaks
- Why skills win: Agent learns preferences and applies consistently
Standard Development - Common programming tasks
- Example: CRUD operations, API endpoints, database migrations
- Why skills win: 35% token savings, faster execution, simpler debugging

✅ Use Multi-Agent When:

True Parallelization - Tasks are genuinely independent and can run simultaneously
- Example: Research 5 different database solutions
- Why multi-agent wins: Wall-clock time reduction, breadth-first coverage
Diversity of Approaches - Want to compare multiple solution strategies
- Example: Implement feature 3 different ways to evaluate trade-offs
- Why multi-agent wins: Stochastic variation provides genuine alternatives
Scale Demands Concurrency - Dataset too large for sequential processing
- Example: Analyze security of 100 microservices
- Why multi-agent wins: Parallel execution reduces total time
Environment Isolation - Operations in truly separate contexts
- Example: Deploy to 10 regional clusters simultaneously
- Why multi-agent wins: Prevents cross-contamination, enables rollback per region

✅ Use Hybrid (Orchestrator + Workers with Skills) When:

Complex Feature with Parallel Sub-Tasks
- Example: E-commerce checkout (payment processing || inventory check || email confirmation)
- Architecture: Orchestrator coordinates, each worker loads relevant skills
- Result: Parallel efficiency + skills token optimization
Multi-Layered System Changes
- Example: Update frontend + backend + database + infrastructure
- Architecture: Worker per layer, each with specialized skills
- Result: Parallel execution with deep expertise per layer

Getting Started with Skills-First

Step 1: Identify Your Common Workflows

# Audit what you do repeatedly
- What coding patterns do you repeat?
- What multi-step processes do you always follow?
- What expertise do you wish your team shared?

Step 2: Convert Workflows to Skills

# Use the skill creation pipeline
skill-seekers docs ./your-documentation/
# Or extract from successful project
skill-seekers github your-org/successful-project --enhance

Step 3: Build a Skills Library

my-skills/
├── backend/
│   ├── fastapi-skill.md
│   ├── database-skill.md
│   └── api-testing-skill.md
├── frontend/
│   ├── react-patterns-skill.md
│   └── accessibility-skill.md
└── devops/
    ├── docker-skill.md
    └── k8s-deploy-skill.md

Step 4: Use Skills in Your Workflow

# In your conversations with Claude:
"Use the fastapi-skill to build this API endpoint"
"Load the database-skill and api-testing-skill for this feature"

# Or invoke via Skill tool:
Uses the Skill tool with skill="fastapi"

Step 5: Measure and Optimize

Track metrics:
- Token usage before vs. after skills adoption
- Time to complete similar tasks
- Consistency across team members
- Knowledge retention (can new members ship faster?)

Typical results:
- 30-40% token reduction
- 25-35% faster task completion
- 50%+ reduction in "how do we do X?" questions

Migration Strategy: From Multi-Agent to Skills

If you already have multiple specialized agents:

# STEP 1: Identify overlap
current_agents:
  - frontend-agent.md (600 lines)
  - backend-agent.md (800 lines)
  - testing-agent.md (500 lines)

common_sections:
  - All three have similar "allowed-tools"
  - All three load project context
  - All three have coding standards
  - Overlap: ~60% of content duplicated

# STEP 2: Extract unique capabilities as skills
create_skills:
  - frontend-skill.md (200 lines of unique patterns)
  - backend-skill.md (300 lines of unique patterns)
  - testing-skill.md (150 lines of unique patterns)

# STEP 3: Create general developer agent
general-agent.md:
  - Common tooling: Read, Edit, Write, Bash, Search
  - Project context: README, CLAUDE.md, architecture docs
  - Skill loading: Can dynamically load any skill as needed
  - Size: 300 lines (vs. 1900 lines across 3 agents)

# STEP 4: Gradual migration
week_1: Use skills-first for new bugs
week_2: Use skills-first for new features
week_3: Deprecate old multi-agent configs
week_4: Full skills-first adoption

results:
  - Maintenance burden: 1 agent + 3 skills vs. 3 agents
  - Token efficiency: 35% improvement
  - Team velocity: 20% faster (less context switching)

Benefits of Skills Approach

35% reduction in token usage through context reuse
Single agent to maintain and configure
Composable capabilities - combine skills for complex workflows
Progressive context loading - load only what's needed per phase
Easier knowledge sharing across teams and projects
Faster onboarding - understand one agent pattern + modular skills

When Multi-Agent Still Makes Sense

Breadth-first parallel tasks - Research across independent sources
Multiple independent workstreams - Concurrent feature development
Exploring alternative approaches simultaneously
Time-sensitive deliverables requiring parallel execution
Large-scale operations needing true concurrency

Hybrid Approach (Best of Both Worlds)

For complex features, combine both patterns:

Orchestrator (Opus 4)
  ↓
Spawns workers (Sonnet 4)
  ↓
Each worker loads appropriate skills dynamically

Result: Parallel execution efficiency + skills-first token optimization

Read More: See Agent Skills vs. Multi-Agent Guide for detailed decision matrices, migration strategies, and performance analysis.

🔄 Integration & Maintenance System

NEW: Automated content ingestion and repository health monitoring.

What is the Integration System?

The Integration System provides automated workflows for:

Ingesting new content - Commands, agents, skills, and documentation
Validating quality - Structure, security, and standards compliance
Integrating seamlessly - Moving files to correct locations and updating docs
Maintaining audit trails - Complete logs of all integration activities

How It Works

Step 0: Generate Skills (NEW) Create skills automatically from documentation, GitHub repos, or PDFs:

# From documentation
/create-skill --url https://fastapi.tiangolo.com --name fastapi

# From GitHub repository
/create-skill --github facebook/react --enhance

# From PDF
/create-skill --pdf /path/to/manual.pdf --name api-guide

Skills are auto-generated and placed in /INTEGRATION/incoming/, ready for integration.

Step 1: Add Content Or manually place files in /INTEGRATION/incoming/:

cp my-new-command.md /INTEGRATION/incoming/

Step 2: Scan

/integration-scan

Categorizes files and generates detailed report (auto-run by /create-skill).

Step 3: Review Check the scan report at /INTEGRATION/logs/scan-report-[timestamp].md

Step 4: Integrate (Coming Soon)

/integration-process    # Move validated files to proper locations
/integration-validate   # Run comprehensive quality checks
/integration-update-docs  # Update all documentation

What is the Maintenance System?

The Maintenance System keeps the repository healthy by:

Identifying stale content - Files not updated in 30+ days
Researching improvements - Latest best practices and patterns
Proposing updates - Concrete action items for evolution
Tracking repository health - Freshness scores and metrics

How It Works

Step 1: Scan for Stale Files

/maintenance-scan

Generates report at /MAINTENANCE/todo/stale-files-[timestamp].md

Step 2: Review Priority Files (Coming Soon)

/maintenance-review path/to/stale-file.md

Research Specialist agent investigates and proposes updates.

Step 3: Update Development Plan (Coming Soon)

/maintenance-plan-update

Adds approved improvements to DEVELOPMENT_PLAN.md

Directory Structure

/INTEGRATION/
├── incoming/     # Drop new files here
├── processed/    # Archive of successfully integrated files
├── failed/       # Files that didn't pass validation
└── logs/         # Scan and integration reports

/MAINTENANCE/
├── reports/      # Research findings and proposals
└── todo/         # Stale file lists and action items

Integration Manager Agent

The Integration Manager orchestrates the entire ingestion pipeline:

Scans incoming directories
Categorizes by type (Command/Agent/Skill/Doc)
Validates against repository standards
Coordinates file movement and documentation updates
Maintains comprehensive audit trails

See: agents-templates/integration-manager.md

Benefits

✅ Consistency - All content follows repository standards

✅ Security - Automated validation catches security issues

✅ Quality - Comprehensive checks before integration

✅ Automation - Reduces manual file management

✅ Audit Trail - Complete history of all changes

✅ Repository Health - Proactive staleness detection

🤖 Automation & CI/CD

NEW: Comprehensive GitHub Actions workflows for automated maintenance, security, and integration.

Automated Workflows

The repository includes 6 production-ready GitHub Actions workflows:

Core Automation

🔧 Maintenance Scan

Schedule: Monthly (1st @ 2 AM UTC)
Purpose: Identifies stale files and generates health reports
Output: GitHub Issue with actionable maintenance tasks
Cost: ~$0.03/month

🔄 Integration Pipeline

Schedule: Hourly during work hours (Mon-Fri 9 AM-5 PM)
Trigger: New files in INTEGRATION/incoming/
Pipeline: Scan → Validate → Process → Create PR
Output: Automated PR for validated files
Cost: ~$1.80/month

📚 Research Monitor

Schedule: Weekly (Monday @ 9 AM UTC)
Sources: Anthropic blog, SDK releases, MCP servers
Output: GitHub Issue with research summary
Downloads: New content to INTEGRATION/incoming/
Cost: ~$0.06/month

Security & Quality

🔒 Security Scanning

Schedule: Daily @ 3 AM UTC + on push/PR
Tools: CodeQL, TruffleHog, ShellCheck, Dependency Review
Output: Security alerts + issues for findings
Cost: Free (GitHub native)

✅ PR Validation

Trigger: All pull requests
Validates: Commands, agents, skills, structure
Includes: Claude code review
Mode: Non-blocking advisory
Cost: ~$1.20/month

🔗 Link Checker

Schedule: Weekly (Wednesday @ 10 AM UTC)
Validates: All markdown links
Output: GitHub Issue if broken links found
Cost: Free

Setup & Configuration

Required Secrets

Configure in repository settings:

Settings → Secrets and variables → Actions

Name: ANTHROPIC_API_KEY
Value: <your-anthropic-api-key>

Testing Workflows

All workflows support manual dispatch:

Go to Actions tab
Select workflow from sidebar
Click Run workflow
Configure inputs (if any)
Click Run workflow

Cost & Monitoring

Total Monthly Cost: ~$3.09 in Anthropic API usage + Free GitHub Actions

Monitoring:

Weekly: Review failed workflows, triage issues, merge PRs
Monthly: Review maintenance report, audit security alerts
Quarterly: Update configurations, rotate API key

Benefits:

✅ Automated Health Checks - Catches stale content early
✅ Security First - Daily scans with multiple tools
✅ Quality Gates - Automated PR validation
✅ Research Tracking - Stay current with Claude ecosystem
✅ Cost Effective - ~$3/month for comprehensive automation
✅ Zero Maintenance - Runs autonomously with human approval gates

Workflow Files

All automation is in .github/:

workflows/maintenance-scan.yml - Monthly health checks
workflows/integration-pipeline.yml - Content processing
workflows/security-scanning.yml - Security audits
workflows/pr-validation.yml - PR quality checks
workflows/research-monitor.yml - Research tracking
workflows/link-checker.yml - Link validation
actions/setup-claude/ - Composite action for Claude CLI
dependabot.yml - Dependency updates
markdown-link-check.json - Link checker config

See CLAUDE.md#github-actions-automation for detailed documentation.

🏗️ Architecture Patterns

Single Agent + Skills Pattern (Recommended Default)

For most workflows, use a general agent that dynamically loads skills:

┌─────────────────────────────────────────────────────────────┐
│                   General Agent (Claude)                    │
│                                                             │
│  Dynamically Loads Skills Based on Task:                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │ Builder  │ │Validator│ │  Scribe  │ │  DevOps  │    │
│  │  Skill   │ │  Skill   │ │  Skill   │ │  Skill   │    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
└─────────────────────────────────────────────────────────────┘

Benefits:

Maintains context across workflow phases
35% more token-efficient than multi-agent
Single agent to configure and maintain
Skills are composable and reusable
Progressive context loading
Easier knowledge sharing

Use For:

Feature implementation (sequential workflows)
Bug fixes and refactoring
Documentation generation
Code reviews and testing
Standard development tasks

The Orchestrator-Worker Pattern (For Parallel Tasks)

Best for breadth-first parallelizable work:

Research across multiple independent sources
Exploring multiple solution approaches simultaneously
Multi-environment deployments
Large-scale concurrent operations

NOT recommended for:

Sequential coding workflows
Single-threaded task execution
When context needs to flow between steps

┌─────────────────────────────────────────────────┐
│         Lead Agent (Orchestrator)               │
│         - Claude Opus 4                         │
│         - Request analysis                      │
│         - Task decomposition                    │
│         - Result synthesis                      │
└────────────┬────────────────────────────────────┘
             │
             │ Spawns & coordinates
             │
    ┌────────┴────────┬──────────┬──────────┐
    │                 │          │          │
┌───▼───┐       ┌─────▼────┐  ┌──▼────┐   ┌─▼─────┐
│Builder│       │Validator │  │Scribe │   │DevOps │
│Sonnet │       │Sonnet    │  │Sonnet │   │Sonnet │
└───────┘       └──────────┘  └───────┘   └───────┘

Key Benefits:

Parallel execution of independent tasks
Cost optimization (efficient models for routine work)
Specialized expertise per domain
Clear responsibility boundaries
Maintainable complexity

When to Use:

Feature development spanning multiple concerns
Complex refactoring requiring testing and documentation
Release preparation with quality gates
Multi-environment deployment orchestration

Modern Hybrid Approach: Orchestrator spawns workers that each load appropriate skills:

┌───────────────────────────┐
│   Orchestrator Agent      │
│   (Opus 4)                │
└───────────┬───────────────┘
            │
   ┌────────┼────────┐
   │        │        │
┌──▼─────┐ ┌▼──────┐ ┌▼──────┐
│Agent 1 │ │Agent 2│ │Agent 3│
│+Skills │ │+Skills│ │+Skills│
└────────┘ └───────┘ └───────┘

Result: Parallel execution + skills-first token efficiency

Multi-Agent Orchestration Patterns

NEW: Advanced patterns for parallel, concurrent multi-agent development with git worktree isolation.

The Hybrid AI Agent Development Pattern

The ultimate productivity pattern: Combine git worktrees with multi-agent orchestration for 3-10x faster development while maintaining code quality.

Why This Pattern Wins

Problem with Sequential Development:

Day 1: Design authentication → 2 hours
Day 1: Implement OAuth → 4 hours
Day 2: Test OAuth → 2 hours
Day 2: Decide JWT might be better → stuck with OAuth
Day 2: Document OAuth → 1 hour
Total: 9 hours, single approach, can't compare alternatives

Solution with Git Worktrees + Multi-Agent:

Hour 1: Design authentication (Architect agent, main branch)
Hour 1-3: Parallel implementation in 3 worktrees:
  ├─ Agent 1 (OAuth) in ../auth-worktree-oauth
  ├─ Agent 2 (JWT) in ../auth-worktree-jwt
  └─ Agent 3 (Session) in ../auth-worktree-session
Hour 3: Compare all 3 implementations
Hour 3: Select best approach (JWT wins)
Hour 3: Merge JWT implementation to main
Total: 3 hours, explored 3 alternatives, picked best
Speedup: 3x faster + higher quality through comparison

Architecture Diagram

┌──────────────────────────────────────────────────────────┐
│            Lead Orchestrator (Claude Opus 4)             │
│  • Decomposes feature into parallel tasks                │
│  • Spawns specialized agents in isolated worktrees       │
│  • Monitors progress and coordinates handoffs            │
│  • Synthesizes results and resolves conflicts            │
└───────────────────────┬──────────────────────────────────┘
                        │
        ┌───────────────┼────────────────┬────────────────┐
        │               │                │                │
        ▼               ▼                ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌────────────┐  ┌─────────────┐
│  Agent 1    │  │  Agent 2    │  │  Agent 3   │  │  Agent 4    │
│  Architect  │  │  Builder    │  │  Builder   │  │  Validator  │
│             │  │  (OAuth)    │  │  (JWT)     │  │             │
│ Worktree:   │  │ Worktree:   │  │ Worktree:  │  │ Worktree:   │
│ ../arch     │  │ ../impl-v1  │  │ ../impl-v2 │  │ ../tests    │
│ Branch:     │  │ Branch:     │  │ Branch:    │  │ Branch:     │
│ feat/design │  │ feat/oauth  │  │ feat/jwt   │  │ feat/tests  │
└─────────────┘  └─────────────┘  └────────────┘  └─────────────┘

All worktrees share the same .git (history, branches, commits)
Each worktree has its own working directory (zero conflicts!)

Key Benefits Explained

1. Massive Speed Gains (3-10x)

Why: Agents work truly in parallel, not sequentially
Example: 4 independent tasks × 2 hours = 2 hours total (vs. 8 hours sequential)
When it matters most: Complex features, exploration tasks, multi-layer systems

2. Zero Merge Conflicts During Development

Why: Each agent has its own working directory
Traditional problem: Agent A modifies file.js while Agent B reads it → corruption
Worktree solution: Agent A modifies ../worktree-a/file.js, Agent B reads ../worktree-b/file.js → perfect isolation
Merge conflicts only happen at integration time (when you choose to merge)

3. Explore Multiple Approaches

Why: Spawn N agents to explore N different solutions
Example: OAuth vs JWT vs Session-based auth
Result: Compare working implementations, not theoretical designs
Bonus: Stochastic LLM variation means genuinely different approaches

4. Clean Git Integration

Why: Worktrees share .git history
Benefit: All commits visible from any worktree
Benefit: Branches created in one worktree visible in all others
Benefit: Easy to compare, cherry-pick, or merge between approaches

5. Resource Efficiency

Disk: Worktrees share .git objects (minimal overhead ~10MB per worktree)
Memory: Each agent runs independently (no blocking)
Cost: Parallel execution reduces wall-clock time = lower developer cost

Step-by-Step Tutorial: Real-World Example

Scenario: Implement a payment processing system with 3 payment providers (Stripe, PayPal, Square)

Step 1: Initial Planning (5 minutes)

# In your main project directory
/orchestrate-feature

# Orchestrator asks: "What feature are you implementing?"
You: "Payment processing with Stripe, PayPal, and Square"

# Creates MULTI_AGENT_PLAN.md:

feature: payment-processing
approach: parallel-exploration
agents:
  - architect-agent: Design payment abstraction layer (main branch)
  - builder-stripe: Implement Stripe integration (worktree)
  - builder-paypal: Implement PayPal integration (worktree)
  - builder-square: Implement Square integration (worktree)
  - validator-agent: Test all integrations (worktree)

dependencies:
  - Architect completes → Builders start
  - All Builders complete → Validator starts

estimated_time: 3-4 hours (vs. 12 hours sequential)

Step 2: Create Worktrees (30 seconds)

# Orchestrator automatically creates worktrees
/spawn-agents

# Creates:
# ../payment-worktree-stripe     (branch: feat/stripe-integration)
# ../payment-worktree-paypal     (branch: feat/paypal-integration)
# ../payment-worktree-square     (branch: feat/square-integration)
# ../payment-worktree-tests      (branch: feat/payment-tests)

# Your filesystem:
myproject/              ← Your current location
../payment-worktree-stripe/    ← Agent 1 workspace
../payment-worktree-paypal/    ← Agent 2 workspace
../payment-worktree-square/    ← Agent 3 workspace
../payment-worktree-tests/     ← Agent 4 workspace

Step 3: Architect Designs Interface (30 minutes)

// Architect agent in main branch creates:
// src/payments/PaymentProvider.ts

interface PaymentProvider {
  processPayment(amount: number, currency: string): Promise<PaymentResult>;
  refund(transactionId: string): Promise<RefundResult>;
  getStatus(transactionId: string): Promise<PaymentStatus>;
}

// Commits to main branch, all worktrees see this immediately

Step 4: Parallel Implementation (2 hours)

# All 3 builder agents work simultaneously in parallel

# Agent 1 in ../payment-worktree-stripe:
cd ../payment-worktree-stripe
# Implements StripePaymentProvider
# Tests with Stripe API
# Commits to feat/stripe-integration

# Agent 2 in ../payment-worktree-paypal:
cd ../payment-worktree-paypal
# Implements PayPalPaymentProvider
# Tests with PayPal SDK
# Commits to feat/paypal-integration

# Agent 3 in ../payment-worktree-square:
cd ../payment-worktree-square
# Implements SquarePaymentProvider
# Tests with Square API
# Commits to feat/square-integration

# NO CONFLICTS - each agent has isolated workspace!

Step 5: Monitor Progress (Continuous)

/coordinate-workflow

# Live status dashboard:
┌─────────────────────────────────────────┐
│   Payment Processing - Live Status     │
├─────────────────────────────────────────┤
│ ✅ Architect: Design complete           │
│ 🔄 Stripe Builder: 80% (testing...)    │
│ 🔄 PayPal Builder: 65% (implementing)  │
│ ✅ Square Builder: 100% (DONE)         │
│ ⏸️  Validator: Waiting for builders     │
└─────────────────────────────────────────┘

Step 6: Compare Implementations (30 minutes)

# All 3 implementations complete
# Orchestrator compares:

Stripe Implementation:
  ✅ Clean code structure
  ✅ Comprehensive error handling
  ⚠️  Requires webhook setup (complexity)
  ⚠️  Higher transaction fees

PayPal Implementation:
  ✅ Familiar UX for users
  ✅ Lower fees than Stripe
  ⚠️  API more complex
  ⚠️  Slower settlement times

Square Implementation:
  ✅ Simplest API integration
  ✅ Best documentation
  ✅ Fastest settlement
  ✅ Lowest fees
  ❌ Limited international support

# Decision: Use Square as primary, keep Stripe as fallback

Step 7: Merge Winner (15 minutes)

# In main project directory
git merge feat/square-integration
git merge feat/stripe-integration  # Keep as backup provider

# Clean up unneeded worktrees
/worktree-setup cleanup

# Removes:
# ../payment-worktree-paypal (implementation discarded)
# ../payment-worktree-tests (tests merged to main)

Step 8: Final Validation (30 minutes)

/quality-gate

# Runs:
✅ Unit tests for Square integration
✅ Unit tests for Stripe integration
✅ Integration tests with test accounts
✅ Security scan (no hardcoded keys)
✅ Documentation completeness
✅ Code review checklist

# Result: PASS - Ready for production

Total Time: 3.5 hours

Sequential approach (one at a time): ~12 hours
Speedup: 3.4x faster
Bonus: Evaluated 3 providers, made informed choice
Bonus: Kept Stripe as backup (diversification)

When to Use This Pattern

✅ Perfect for:

Complex features with multiple valid approaches
Exploring 2-5 alternative implementations
Full-stack features (FE + BE + DB all in parallel)
Large refactorings affecting multiple modules
POCs where you need to compare solutions

❌ Overkill for:

Simple bug fixes
Features with one obvious implementation
Tasks requiring deep context sharing between steps
Quick documentation updates

Orchestration Command Templates

Command	Purpose	Execution Time
orchestrate-feature	Multi-agent feature orchestration with parallel task execution	90-120 min for complex features
spawn-agents	Dynamic agent instantiation with role assignment and resource allocation	< 1 min per agent
coordinate-workflow	Real-time inter-agent communication and progress tracking	Continuous monitoring
worktree-setup	Git worktree lifecycle management and cleanup automation	< 10 sec per worktree
quality-gate	Multi-stage validation pipeline with parallel test execution	20-30 min validation

Orchestration Agent Templates

Agent	Model	Purpose	Cost Optimization
Orchestrator Lead	Claude Opus 4	Request decomposition, agent spawning, result synthesis	High capability for planning
Task Coordinator	Claude Sonnet 4	Dependency management, parallel optimization, bottleneck detection	Efficient for coordination
Integration Orchestrator	Claude Sonnet 4	Result merging, conflict resolution, final validation	Efficient for integration
Monitoring Agent	Claude Haiku 3.5	Real-time tracking, metrics collection, cost monitoring	Minimal cost for monitoring

Orchestration Skills

Skill	Purpose	Integration
multi-agent-planner-skill	Automated MULTI_AGENT_PLAN.md generation with dependency analysis	Orchestrate-feature command
parallel-executor-skill	Concurrent task execution with work distribution and result aggregation	Spawn-agents, coordinate-workflow
worktree-manager-skill	Git worktree lifecycle management and merge strategies	Worktree-setup command
agent-communication-skill	Inter-agent messaging and handoff documentation	Coordinate-workflow command

Decision Matrix: When to Use Multi-Agent Orchestration

Scenario	Use Orchestration?	Recommended Pattern
Simple bug fix (< 100 lines)	❌ No	Single Builder agent
Feature with clear implementation (< 500 lines)	❌ No	Single Builder + Validator
Complex feature with multiple approaches	✅ Yes	Parallel builders + comparison
Large refactoring (multi-module)	✅ Yes	Architect + parallel builders
Full-stack feature (FE + BE + DB + Tests + Docs)	✅ Yes	Specialized agents per layer
Exploring technical solutions (POC)	✅ Yes	Parallel researchers

Git Worktree Integration Strategy

Lightweight Isolation (default for trusted code):

Setup time: < 1 second per worktree
Disk overhead: Minimal (shared .git)
Isolation level: Filesystem only
Use case: Parallel feature variants, rapid prototyping

Container-Based Isolation (security-critical):

Setup time: 1-3 minutes per container
Disk overhead: High (per-container layers)
Isolation level: Full process isolation
Use case: Untrusted code, compliance requirements

Hybrid Approach (production systems):

Containers for primary isolation
Worktrees within containers for lightweight filesystem separation
Defense-in-depth security
Resource quotas enforced at container level

🔒 Security & Safety

Core Security Principles

Least Privilege: Grant minimum necessary permissions per agent/command
Explicit Allowlists: Use allowed-tools to restrict operations
Input Validation: Sanitize all dynamic values and user inputs
Approval Gates: Require human confirmation for critical operations
Audit Logging: Maintain detailed logs of all agent actions
Rollback Capability: Design for safe recovery from failures

Permission Model

# Restrictive (default for most commands)
allowed-tools: ["Read", "Search"]

# Development (standard builder agent)
allowed-tools: ["Read", "Search", "Edit", "Test", "Bash(git:*)"]

# Operations (devops with infrastructure access)
allowed-tools: ["Read", "Edit", "Bash(git:*)", "Bash(docker:*)", "Bash(kubectl:*)"]

# NEVER grant unrestricted access
# ❌ allowed-tools: ["Bash(*)"]  # Dangerous!

🎓 Best Practices

Command Creation

✅ Do:

Use descriptive verb-noun naming (/prepare-pr, /deploy-check)
Specify explicit allowed-tools restrictions
Include comprehensive inline documentation
Implement error handling and validation
Version semantic changes (1.0 → 1.1)

❌ Don't:

Hardcode project-specific values
Grant excessive permissions
Create monolithic multi-purpose commands
Skip input validation
Forget to document expected behavior

Agent Configuration

✅ Do:

Define clear, focused roles
Document responsibilities explicitly
Implement context isolation
Create handoff protocols
Test agent interactions

❌ Don't:

Create generalist "do everything" agents
Allow unscoped context pollution
Skip security boundary definitions
Forget collaboration patterns
Neglect memory management

Multi-Agent Orchestration

✅ Do:

Use orchestrator-worker pattern
Create MULTI_AGENT_PLAN.md for coordination
Define clear communication protocols
Implement parallel execution where possible
Handle errors gracefully with recovery

❌ Don't:

Create circular dependencies
Skip dependency mapping
Neglect error propagation
Forget result validation
Ignore cost optimization

🚀 Getting Started

Installation

For Personal Use:

# Clone repository
git clone https://github.com/enuno/claude-command-and-control.git

# Copy templates to your Claude commands directory
cp -r templates/commands/* ~/.claude/commands/

# Copy agent templates to your project
cp -r templates/agents/* ./.claude/agents/

For Team/Organization:

# Add as submodule to your project
git submodule add https://github.com/enuno/claude-command-and-control.git docs/claude

# Reference in your CLAUDE.md
echo "Import command and agent standards from docs/claude/" >> CLAUDE.md

Usage Examples

Create a Development Session:

# Initialize session with context
/start-session

# Plan work for the session
/plan

# Make changes...

# Close session with summary
/close-session

Multi-Agent Feature Development:

# Architect agent: Create development plan
/plan feature/user-authentication

# Builder agent: Implement feature
# (automated via MULTI_AGENT_PLAN.md)

# Validator agent: Run tests and review
/test-all

# Scribe agent: Generate documentation
/docs

# DevOps agent: Prepare deployment
/pr

Quality Assurance Workflow:

# Check environment
/env-check

# Run full test suite
/test-all

# Fix linting issues
/lint-fixes

# Update dependencies
/deps-update

# Clean workspace
/cleanup

📊 Success Metrics

Organizations using these patterns report:

28.4% reduction in operational costs through efficient model selection
96.7% maintained performance quality with optimized architectures
40% faster feature delivery with multi-agent parallelization
60% reduction in human code review time through automated validation
Zero security incidents when following security best practices

⚡ Command Quick Reference

Your go-to cheat sheet for all Claude Code commands and workflows.

Essential Session Management

Command	Purpose	When to Use	Example
`/start-session`	Initialize coding session with project context	Start of every work session	Beginning of day, after context switch
`/close-session`	End session with summary and documentation	End of work session	End of day, before switching projects
`/plan`	Generate or update development plan	Planning new features or refactors	Before starting complex work
`/summarize`	Summarize recent work and changes	Need quick recap of progress	Standups, handoffs to teammates

Quality Assurance & Testing

Command	Purpose	When to Use	Example
`/test-all`	Run complete test suite (unit + integration + e2e)	Before commits, before PRs	After feature completion
`/lint-fixes`	Auto-fix code style and linting issues	Clean up code before review	Before creating PR
`/deps-update`	Check and update outdated dependencies	Weekly maintenance, security patches	Monday morning routine
`/error-report`	Generate diagnostic report for failures	Tests or builds failing	Debugging CI failures
`/env-check`	Validate development environment setup	Environment issues suspected	Onboarding, after system updates

Development Workflow

Command	Purpose	When to Use	Example
`/pr`	Create pull request with auto-generated description	Feature complete and tested	After `/test-all` passes
`/docs`	Generate or update documentation	API changes, new features	After public API modifications
`/search`	Search codebase for patterns or keywords	Finding specific code or usage	Locating implementation examples
`/cleanup`	Clean temporary files, old branches, unused configs	Workspace maintenance	Weekly cleanup routine

Multi-Agent Orchestration

Command	Purpose	When to Use	Execution Time
`/orchestrate-feature`	Decompose feature into parallel tasks, create plan	Complex features (> 500 LOC)	5-10 min planning
`/spawn-agents`	Instantiate specialized agents in isolated worktrees	After orchestrate-feature	< 1 min per agent
`/coordinate-workflow`	Monitor multi-agent progress in real-time	During parallel execution	Continuous
`/quality-gate`	Run comprehensive validation before merge	Before integrating parallel work	20-30 min
`/worktree-setup`	Manage git worktree lifecycle and cleanup	Setup or cleanup worktrees	< 10 sec per worktree

Integration & Maintenance

Command	Purpose	When to Use	Execution Time
`/integration-scan`	Scan and categorize files in INTEGRATION/incoming/	New content to integrate	1-3 min
`/integration-update-docs`	Update documentation after successful integration	After integration-scan passes	30 sec
`/maintenance-scan`	Identify stale content (> 30 days old)	Monthly repository health check	2-5 min
`/create-skill`	Generate skill from docs/GitHub/PDF	Creating new reusable workflows	5-30 min

Common Workflows

Daily Development Flow

# Morning
/start-session              # Load project context
/plan                       # Review today's goals
# ... code ...
/test-all                   # Validate changes
/lint-fixes                 # Clean up style
/pr                         # Create pull request
/close-session             # End day with summary

Weekly Maintenance Flow

/maintenance-scan          # Identify stale content
/deps-update               # Check for updates
/cleanup                   # Remove unused files
/docs                      # Update documentation

Feature Development with Multi-Agent

/orchestrate-feature       # Plan parallel tasks
/spawn-agents              # Create isolated workspaces
/coordinate-workflow       # Monitor progress
/quality-gate              # Validate before merge
/worktree-setup cleanup    # Clean up worktrees

Skill Creation Flow

# Generate from source
skill-seekers docs ./documentation/
# OR
skill-seekers github owner/repo --enhance
# OR
skill-seekers pdf manual.pdf

# Integrate
cp output/*/SKILL.md INTEGRATION/incoming/
/integration-scan           # Validate
/integration-update-docs    # Update indices

Command Flags & Options

/test-all

/test-all                   # Run all tests
/test-all --unit            # Unit tests only
/test-all --integration     # Integration tests only
/test-all --coverage        # With coverage report

/create-skill

/create-skill --url https://docs.example.com --name example
/create-skill --github owner/repo --enhance
/create-skill --pdf manual.pdf --name manual-skill

/worktree-setup

/worktree-setup create <name> <branch>    # Create new worktree
/worktree-setup list                      # List all worktrees
/worktree-setup cleanup                   # Remove all worktrees
/worktree-setup cleanup <name>            # Remove specific worktree

Keyboard Shortcuts & Aliases

Recommended shell aliases (add to .bashrc or .zshrc):

alias c='/start-session'
alias qa='/test-all && /lint-fixes'
alias ship='/test-all && /lint-fixes && /pr'
alias maintain='/maintenance-scan && /deps-update && /cleanup'

Troubleshooting Common Issues

Issue	Command to Fix	Prevention
Tests failing	`/test-all --verbose`	Run `/test-all` before committing
Linting errors	`/lint-fixes`	Enable pre-commit hooks
Outdated dependencies	`/deps-update`	Weekly `/deps-update` routine
Environment broken	`/env-check`	Document environment requirements
Stale documentation	`/docs`	Update docs with code changes
Messy workspace	`/cleanup`	Weekly `/cleanup` routine
Worktree conflicts	`/worktree-setup cleanup`	Clean after each feature

Pro Tips

💡 Combine commands in sequences:

# Pre-PR checklist
/test-all && /lint-fixes && /docs && /pr

💡 Use command output in scripts:

# Automated quality gate
if /test-all; then
  /pr
else
  /error-report
fi

💡 Create custom workflows:

# Create new command that combines others
# See: docs/best-practices/02-Individual-Command-Creation.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

Code of conduct
Development workflow
Contribution guidelines
Review process
Style standards

Ways to Contribute

📝 Improve documentation clarity
🎨 Add new command/agent templates
🐛 Report issues or bugs
💡 Suggest enhancements
🔍 Review pull requests
📚 Share usage examples

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This manual synthesizes best practices from:

Anthropic: Official Claude documentation and agent SDK patterns
Production Teams: Real-world implementations across enterprise organizations
Community: Open-source contributions and empirical research
Academia: Studies on agent efficiency, safety, and effectiveness
Security Experts: Frameworks for secure AI agent deployments

📞 Support

Community

Resources

🗺️ Roadmap

Current Version: 1.1

Completed in 1.1 (January 2026):

Advanced orchestration patterns - Document 15 with 6 enterprise-grade patterns (DAG execution, agent pools, distributed state, saga pattern, circuit breakers, performance profiling)
CI/CD integration templates - Complete GitHub Actions automation system (6 workflows, security scanning, automated maintenance)
Extended agent role library - Added 6 specialized orchestration agents (DAG orchestrator, pool manager, state manager, resilience orchestrator, performance monitor, general skills-first agent)
Production orchestration skills - 6 advanced skill templates with algorithm implementations (Kahn's, CRDT, saga pattern, circuit breaker)
Working examples - 5 comprehensive real-world examples with performance metrics

Remaining for 1.2 (Q1 2026):

Performance benchmarking tools
Multi-language command support

Planned for 2.0 (Q2 2026):

Interactive command builder
Visual orchestration designer
Real-time collaboration tools
Cloud-hosted template library
Integration with popular IDEs

📈 Project Stats

Documentation: 15 comprehensive best practice manuals (including Document 15: Advanced Orchestration Patterns)
Active Commands: 13 production-ready commands
Agent Templates: 15 specialized agent configurations (10 base + 5 orchestration)
Command Templates: 27 command templates (21 base + 6 orchestration)
Production Skills: 20 working skills in skills/
Skill Templates: 35 skill templates (29 base + 6 orchestration)
Orchestration Examples: 5 comprehensive real-world examples with metrics
Processed Skills: 30 integrated skills in INTEGRATION/processed/
Code Examples: 100+ working examples across all categories
Best Practices: 100+ documented patterns
Security Guidelines: Comprehensive threat model and audit protocols
Test Coverage: All templates validated
GitHub Actions: 6 automated workflows (maintenance, integration, security, PR validation, link checking, research monitoring)

🌟 Star History

If you find this project useful, please consider starring it on GitHub to help others discover it!

Built with ❤️ by the AI Engineering Community

Version: 1.1.0 Last Updated: January 22, 2026 Maintained By: @enuno Status: ✅ Production Ready

Name		Name	Last commit message	Last commit date
Latest commit History 177 Commits
.claude		.claude
.github		.github
INTEGRATION		INTEGRATION
MAINTENANCE		MAINTENANCE
REFACTOR		REFACTOR
agents-templates		agents-templates
commands-templates		commands-templates
configs		configs
docs		docs
examples/orchestration		examples/orchestration
scripts		scripts
skills-templates		skills-templates
skills		skills
templates		templates
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
ADVANCED_ORCHESTRATION_PLAN.md		ADVANCED_ORCHESTRATION_PLAN.md
AGENT_STRATEGY_UPDATE_SUMMARY.md		AGENT_STRATEGY_UPDATE_SUMMARY.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLAUDE_CODE_INTEGRATION_PLAN.md		CLAUDE_CODE_INTEGRATION_PLAN.md
CLAUDE_CODE_INTEGRATION_VALIDATION.md		CLAUDE_CODE_INTEGRATION_VALIDATION.md
CLAUDE_MD_OPTIMIZATION_PLAN.md		CLAUDE_MD_OPTIMIZATION_PLAN.md
CLAUDE_OPTIMIZATION_SUMMARY.md		CLAUDE_OPTIMIZATION_SUMMARY.md
DEVELOPMENT_PLAN.md		DEVELOPMENT_PLAN.md
FASTMCP_SKILL_IMPLEMENTATION_PLAN.md		FASTMCP_SKILL_IMPLEMENTATION_PLAN.md
INTEGRATION_PLAN.md		INTEGRATION_PLAN.md
INTEGRATION_SUMMARY.md		INTEGRATION_SUMMARY.md
INTEGRATION_VALIDATION.md		INTEGRATION_VALIDATION.md
MIGRATION.md		MIGRATION.md
ORCHESTRATION_IMPLEMENTATION_SUMMARY.md		ORCHESTRATION_IMPLEMENTATION_SUMMARY.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
session-work.md		session-work.md

enuno/claude-command-and-control

Folders and files

Latest commit

History

Repository files navigation

Claude Command and Control

GitHub Actions Status

📑 Table of Contents

Quick Start

Core Concepts

Getting Started Workflows

Architecture & Patterns

Best Practices & Security

Advanced Topics

Contributing & Community

📚 Overview

What You'll Find Here

📂 Repository Structure

Key Directories Explained

🎯 Quick Start

For Developers

For AI Coding Assistants

For Multi-Agent Orchestration (NEW)

📖 Documentation Structure

Core Instruction Manuals

Reference Documentation

📚 Learning Paths

🎯 Path 1: Quick Start (30 minutes)

👨‍💻 Path 2: Developer Onboarding (2 hours)

🏗️ Path 3: Architecture & Planning (3 hours)

🔧 Path 4: Skills Builder (1.5 hours)

🎯 Path 5: Problem-Specific Guides

📊 Path 6: Team Lead / Manager (1 hour)

🎓 Recommended Reading Order by Experience Level

🎨 Template Library

Agent Templates

Orchestration Agent Templates

Command Templates

Core Workflow Commands

Quality Assurance Commands

Utility Commands

Integration & Maintenance Commands

Multi-Agent Orchestration Commands

Orchestration Planning Templates

🎯 Claude Skills

What Are Skills?

Getting Started with Skills

🎨 End-to-End Skill Creation Workflow

Why Create Skills?

Overview: The 4-Step Pipeline

Step 1: Generate Skill from Source

Option A: From Documentation Files

Option B: From GitHub Repository

Option C: From PDF Manual

Step 2: Review Scan Report

Step 3: Validate & Process

Step 4: Update Documentation

Result: Production-Ready Skill

Timeline Reference

Troubleshooting Common Issues

Pre-Built Skills

Orchestration Skills (NEW)

Resources

🧠 The Skills-First Paradigm

Why Skills Win: The Research

The Paradigm Shift

Real-World Examples

Example 1: Bug Fix Workflow

Example 2: Feature Implementation

Example 3: Code Review

Decision Framework: When to Use What

Detailed Decision Criteria

Getting Started with Skills-First

Migration Strategy: From Multi-Agent to Skills

Benefits of Skills Approach

When Multi-Agent Still Makes Sense

Hybrid Approach (Best of Both Worlds)

🔄 Integration & Maintenance System

What is the Integration System?

How It Works