How to Create Multi-Agent Workflows Using Claude Plugins

You create multi-agent workflows using plugins by installing a plugin that exposes skills—defined in SKILL.md files—which Claude uses to spawn isolated sub-agents that can share state through an MCP server and synchronize results via built-in synthesis commands.

The anthropics/claude-plugins-community repository demonstrates how to build sophisticated multi-agent workflows using plugins, where each plugin acts as a container for specialized agents, skills, and commands. By leveraging the plugin architecture found in this repository, you can orchestrate parallel agent execution, manage state through GraphQL endpoints, and synthesize outputs from multiple AI personalities into coherent decisions.

Architecture of Multi-Agent Plugins

Plugin Metadata and Configuration

Every multi-agent plugin starts with .claude-plugin/plugin.json, which declares the plugin name, description, and optional userConfig schema. This file serves as the entry point for Claude to load the plugin and validate user-specific settings like API keys. According to the source code, the plugin lives under ~/.claude/plugins/<name>/, ensuring isolation where the LLM only sees declared skills while internal files remain hidden unless explicitly exposed.

Skills as Agent Entry Points

Skills are the core mechanism for creating multi-agent workflows. Stored as SKILL.md files in directories like skills/16minds/mind/SKILL.md, these Markdown files describe reusable capabilities that Claude exposes as slash-commands (e.g., /mind, /pair). When invoked with a type argument, Claude injects the corresponding personality prompt into the LLM's system prompt, creating an isolated reasoning context distinct from the main conversation.

The MCP Server for State Management

The .mcp.json file defines an MCP (Model Context Protocol) server that provides GraphQL tools like build_query and execute. This enables agents to share state without leaking secrets or requiring direct file access. Skills can call execute queries to read from or write to a shared JSON store, allowing coordination across agent boundaries while maintaining security boundaries defined in the plugin configuration.

Building a Multi-Agent Workflow

Step 1 – Install the Plugin

Begin by adding the plugin to your Claude environment:

claude plugin marketplace add anthropics/claude-plugins-community

This command pulls the plugin into ~/.claude/plugins/anthropics-claude-plugins-community/ and validates the .claude-plugin/plugin.json manifest against your local configuration.

Step 2 – Invoke Skills to Spawn Agents

Once installed, you invoke skills to create specialized agents. The 16 minds plugin provides three command families defined in skills/16minds/:

• /mind <type> – Spins up a single personality agent
• /pair <a> <b> – Runs a two-person debate with rebuttals and synthesis
• /minds – Fans out all 16 personalities in parallel, then synthesizes a final report

As noted in .claude-plugin/marketplace.json (lines 44-48), these commands cover the full range from focused single-agent queries to comprehensive decision-making panels where "a single averaged answer would lose the edges."

Step 3 – Chain Agents for Complex Tasks

Multi-agent workflows progress by chaining agent outputs. The /pair skill internally calls the /mind skill twice to generate opening statements, then orchestrates a rebuttal phase before invoking a /synthesize helper to merge perspectives. Similarly, the /minds command loops over 16 personality prompts, issues concurrent LLM calls, and applies a fixed 4-section rubric covering Score distribution, Axes of disagreement, Overlooked perspectives, and Landing-zone candidates.

Practical Examples from the 16 Minds Plugin

Summoning a Single Agent

To instantiate a skeptic personality that challenges assumptions:

/mind skeptic

Claude parses this command using the definition in skills/16minds/mind/SKILL.md, loading the "skeptic" prompt into a sub-agent's system context.

Running a Two-Person Debate

To orchestrate a debate between optimistic and pessimistic viewpoints:

/pair optimistic pessimistic

This creates two isolated agents that generate opening statements, respond to rebuttals, and produce a synthesized conclusion through the orchestration logic defined in skills/16minds/pair/SKILL.md.

Fanning Out All 16 Agents

For complex decisions requiring diverse perspectives:

/minds

This command parallelizes execution across all 16 personality types defined in the plugin, then aggregates outputs into a structured JSON report. You can persist the full transcript for later analysis:

/minds --save ./minds-report.json

Sharing Data via MCP

Skills can query shared state through the MCP server defined in .mcp.json:

query GetProjectInfo {
  project(id: "my-project") {
    name
    repoUrl
  }
}

The skill calls execute against the plugin's GraphQL endpoint, retrieving metadata that subsequent agents can reference without direct file system access.

State Sharing and Parallelism

The plugin architecture handles parallelism via concurrent LLM calls in the /minds implementation, while safety is enforced through the userConfig schema—API keys like DEBANK_API_KEY are read from the user's local config file rather than exposed to the LLM prompt. The MCP server acts as a secure broker, allowing agents to coordinate through a shared JSON store without breaking isolation boundaries between plugin directories.

Summary

• Plugin structure: Multi-agent workflows require .claude-plugin/plugin.json for metadata and skills/*/SKILL.md files defining slash-commands that spawn agents.
• Agent isolation: Each skill invocation creates a distinct system prompt context, ensuring agents operate with specialized personas without cross-contamination.
• Orchestration patterns: Chain agents using skills that call other skills (e.g., /pair invoking /mind twice) to build complex debate and synthesis workflows.
• State management: The .mcp.json MCP server provides GraphQL endpoints for secure data sharing between parallel agent executions.
• Parallel execution: The /minds command demonstrates fan-out patterns where 16 agents run concurrently before structured synthesis.

Frequently Asked Questions

What is the difference between a skill and a command in Claude plugins?

Skills are high-level capabilities defined in SKILL.md files that Claude exposes as slash-commands to the user, while commands (defined in COMMAND.md files) are low-level tool wrappers for external services like HTTP calls. In the 16 minds plugin, /mind and /pair are skills that orchestrate LLM-based agents, whereas commands would typically wrap APIs for data retrieval or computation.

How do plugins maintain isolation between agents?

Each plugin resides in ~/.claude/plugins/<name>/ with strict file boundaries. When a skill spawns an agent, Claude injects only the specified personality prompt into that agent's system context, creating a reasoning bubble isolated from the main conversation and other agents. The LLM cannot access internal plugin files unless explicitly exposed through the skill definition.

Can I create custom multi-agent workflows beyond the 16 minds example?

Yes. You can create custom workflows by defining new SKILL.md files in a skills/ directory within your plugin. Follow the pattern in skills/16minds/minds/SKILL.md to implement parallel loops over agent types, or create sequential chains where skills invoke other skills. Reference the .claude-plugin/marketplace.json format to register your plugin with the Claude marketplace.

How does state persistence work across agent boundaries?

State persistence leverages the MCP server configuration in .mcp.json, which exposes GraphQL mutation and query endpoints. Agents call these endpoints through the execute tool to read or write shared JSON objects. This approach allows state synchronization without file system access, and the synthesis step can persist final outputs using flags like --save to write JSON transcripts to specified file paths.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}