agent-skill-creator/references/multi-agent-guide.md

Multi-Agent Suite Creation

Overview

A multi-agent suite is a collection of related skills that work together as a unified system. Instead of creating one monolithic skill, the suite splits responsibilities across multiple focused skills that share references and coordinate through a common integration layer.

The 5-phase pipeline applies to each component skill, but Phase 3 (Architecture) makes the critical decision: simple skill vs. complex suite.

When to Use Batch Creation

Scenario	Single Skill	Multi-Agent Suite
1-2 distinct workflows	Recommended	Overkill
3+ distinct workflows	Unwieldy	Recommended
Total code > 2,000 lines	Hard to maintain	Organized by component
Team maintenance	Single owner ok	Multiple contributors benefit
Shared data sources across workflows	Duplicated logic	Shared reference layer
Independent scaling of capabilities	Not possible	Each skill evolves independently

Rule of thumb: If you find yourself describing more than two unrelated tasks in a single skill description, you need a suite.

Suite Creation Process

Step 1: Analyze Relationships

The system examines the user's requirements and identifies distinct workflow clusters.

User: "I need to track our e-commerce store -- monitor sales,
       analyze customer behavior, track inventory levels, and
       generate executive reports."

Analysis:
  Cluster 1: Sales Monitoring (revenue, orders, conversion)
  Cluster 2: Customer Analytics (segmentation, cohorts, churn)
  Cluster 3: Inventory Tracking (stock levels, reorder alerts)
  Cluster 4: Executive Reporting (aggregated dashboards)

  Shared resources: Shopify API connection, date utilities,
  report generation templates

Step 2: Determine Structure

Based on the cluster analysis, the system designs the suite directory:

ecommerce-suite/
├── SKILL.md                        # Suite-level overview (<500 lines)
├── .claude-plugin/
│   └── marketplace.json            # Suite manifest (official fields only)
├── skills/
│   ├── sales-monitor/
│   │   ├── SKILL.md                # Sales-specific instructions
│   │   └── scripts/
│   │       └── monitor_sales.py
│   ├── customer-analytics/
│   │   ├── SKILL.md                # Customer-specific instructions
│   │   └── scripts/
│   │       └── analyze_customers.py
│   ├── inventory-tracker/
│   │   ├── SKILL.md                # Inventory-specific instructions
│   │   └── scripts/
│   │       └── track_inventory.py
│   └── executive-reports/
│       ├── SKILL.md                # Reporting instructions
│       └── scripts/
│           └── generate_reports.py
├── shared/
│   ├── api_client.py               # Shared Shopify API connection
│   ├── date_utils.py               # Common date handling
│   └── report_templates/           # Shared report assets
│       └── executive_template.html
├── references/
│   └── api-guide.md                # Shared API documentation
├── install.sh                      # Installs entire suite
└── README.md                       # Multi-platform instructions

Step 3: Create Individual Skills

Each component skill goes through Phases 1-5 independently, but with awareness of the shared resources:

1. Discovery -- Each skill identifies its specific API endpoints (e.g., sales-monitor uses Shopify Orders API, inventory-tracker uses Shopify Inventory API).
2. Design -- Each skill defines its own analyses, scoped to its cluster.
3. Architecture -- Each skill follows the simple skill structure within the suite.
4. Detection -- Each skill gets its own description and keywords for independent activation.
5. Implementation -- Each skill references shared utilities from shared/.

Step 4: Integration Layer

The suite-level SKILL.md serves as the orchestration layer. It describes how the component skills relate and when to invoke which one:

# E-commerce Suite

## Component Skills

This suite contains four specialized skills:

- **sales-monitor**: Activate for revenue, orders, and conversion queries
- **customer-analytics**: Activate for segmentation, cohort, and churn queries
- **inventory-tracker**: Activate for stock levels, reorder, and supply queries
- **executive-reports**: Activate for dashboards, summaries, and executive briefings

## Cross-Skill Workflows

When the user asks for a "full store overview" or "weekly executive summary",
invoke executive-reports which aggregates data from all three other skills.

Suite-Level marketplace.json

For complex suites that need Claude Code plugin registration, a marketplace.json is generated with only official fields:

{
  "name": "ecommerce-suite",
  "plugins": [
    {
      "name": "sales-monitor",
      "description": "Monitor e-commerce sales, revenue trends, order volumes, and conversion rates using Shopify data.",
      "source": "./skills/sales-monitor/",
      "skills": ["./skills/sales-monitor/"]
    },
    {
      "name": "customer-analytics",
      "description": "Analyze customer behavior, segmentation, cohort retention, and churn patterns from e-commerce data.",
      "source": "./skills/customer-analytics/",
      "skills": ["./skills/customer-analytics/"]
    },
    {
      "name": "inventory-tracker",
      "description": "Track inventory stock levels, predict reorder points, and alert on low-stock items.",
      "source": "./skills/inventory-tracker/",
      "skills": ["./skills/inventory-tracker/"]
    },
    {
      "name": "executive-reports",
      "description": "Generate executive dashboards and PDF summaries aggregating sales, customer, and inventory data.",
      "source": "./skills/executive-reports/",
      "skills": ["./skills/executive-reports/"]
    }
  ]
}

Important: The marketplace.json uses ONLY the official fields: name and plugins at the top level, and name, description, source, skills per plugin entry. No version, author, repository, tags, icon, or other non-standard fields.

Suite Examples

Financial Suite

User request: "Create a suite for comprehensive financial analysis -- stock tracking, portfolio management, and market research."

financial-suite/
├── SKILL.md
├── .claude-plugin/marketplace.json
├── skills/
│   ├── stock-tracker/         # Real-time and historical price data
│   ├── portfolio-manager/     # Holdings, allocation, performance
│   └── market-research/       # Sector analysis, news sentiment
├── shared/
│   ├── market_data_client.py  # Alpha Vantage + Yahoo Finance
│   └── financial_utils.py     # Common calculations (returns, ratios)
├── references/
├── install.sh
└── README.md

E-commerce Suite

User request: "I manage an online store and need to track everything -- sales, customers, inventory, and generate weekly reports."

(See the detailed structure in the Suite Creation Process section above.)

Climate Suite

User request: "Build a climate analysis system with historical trend analysis, forecast monitoring, and extreme event alerting."

climate-suite/
├── SKILL.md
├── .claude-plugin/marketplace.json
├── skills/
│   ├── historical-trends/     # Long-term climate data analysis
│   ├── forecast-monitor/      # Short-term forecast tracking
│   └── extreme-events/        # Severe weather alerting
├── shared/
│   ├── climate_data_client.py # NOAA + Open-Meteo connections
│   └── geo_utils.py           # Geographic region handling
├── references/
├── install.sh
└── README.md

Benefits of Suite Creation

Time Efficiency

Creating a suite through the batch process is significantly faster than creating individual skills separately:

Approach	API Research	Shared Code	Integration	Total
4 separate skills	4x (redundant)	0 (duplicated)	Manual	~4 hours
1 suite (batch)	1x (shared)	1x (reused)	Automatic	~1.5 hours

Built-in Integration

Component skills within a suite share:

• API client code (no duplicated connection logic)
• Utility functions (date handling, formatting, calculations)
• Reference documentation (API guides written once)
• Report templates (consistent styling across outputs)

Independent Maintenance

Each component skill can be:

• Updated independently without affecting others
• Tested in isolation
• Replaced with an improved version
• Extended with new analyses

The suite structure makes it possible to update the inventory-tracker without touching the sales-monitor, while still sharing the underlying Shopify API client.

Marketplace Discoverability

Each plugin entry in marketplace.json has its own description and keywords. This means a suite's individual components can be discovered by different searches:

• "track sales" finds the sales-monitor plugin
• "customer churn" finds the customer-analytics plugin
• "inventory alerts" finds the inventory-tracker plugin

The suite functions as both a single installable unit and a collection of independently discoverable capabilities.