# How to Create Multi-Agent Workflows Using Claude Plugins

> Learn to create multi-agent workflows with Claude plugins. Install plugins that expose skills for Claude to spawn isolated sub-agents, sharing state and synchronizing results efficiently.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-13

---

**You create multi-agent workflows using plugins by installing a plugin that exposes skills—defined in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in directories like [`skills/16minds/mind/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```bash
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```text
/mind skeptic

```

Claude parses this command using the definition in [`skills/16minds/mind/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```text
/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`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/16minds/pair/SKILL.md).

### Fanning Out All 16 Agents

For complex decisions requiring diverse perspectives:

```text
/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:

```text
/minds --save ./minds-report.json

```

### Sharing Data via MCP

Skills can query shared state through the MCP server defined in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json):

```graphql
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files that Claude exposes as slash-commands to the user, while **commands** (defined in [`COMMAND.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in a `skills/` directory within your plugin. Follow the pattern in [`skills/16minds/minds/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.