How to use the Multi-Agent Architecture Patterns agent skill

What the skill makes the agent do

The skill's central point is that sub-agents exist mainly to isolate context, not to act out organisational roles. When a single agent's context fills with history, documents and tool outputs and performance degrades, splitting work across agents with fresh contexts can help. The skill also says that extra agents cost substantially more tokens, so the agent is directed to compare a multi-agent setup against a single-agent baseline rather than assume it is better.

When the skill is active, the agent can compare the three patterns it describes: supervisor/orchestrator for centralised control with clear decomposition, peer-to-peer/swarm for flexible exploration with explicit handoffs, and hierarchical for large projects with layered strategy, planning and execution. It also explains trade-offs such as the telephone game, where a supervisor paraphrases worker responses and loses detail, and error propagation between agents.

• Decide whether multiple agents are justified for a task
• Choose a coordination pattern: supervisor, swarm or hierarchical
• Reduce information loss, for example with a forward_message approach
• Reuse coordination building blocks from scripts/coordination.py

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill folder contains SKILL.md, references/frameworks.md and scripts/coordination.py. Put the folder where your agent runtime looks for skills: either your user-level skills folder at ~/.claude/skills/, or a project-level .claude/skills/ folder inside the project you are working on.

If you use the Claude apps instead of a local setup, you can upload the skill under Settings → Capabilities → Skills.

• User-wide: unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description says it should be used when designing multi-agent systems that need context isolation, supervisor or swarm coordination, explicit handoffs, parallel execution, or a decision on whether multiple agents are justified. Describe your design problem in those terms and the agent can load it.

Good requests name the situation, not just the topic. Include what the tasks are, how they split, and what you are worried about, such as cost or reliability.

• "Should this research pipeline use several agents or one? Each source needs about 20 documents read."
• "Design a supervisor that routes customer questions to billing and technical specialists."
• "Compare swarm handoffs with a supervisor for an exploratory coding task where requirements change."
• "Our supervisor paraphrases worker answers and the details are lost. How do we fix that?"

What you need before you start

The skill's files are guidance plus a Python helper. You need Python to run scripts/coordination.py, and an agent runtime that supports SKILL.md skills. The files shown require no API keys or accounts. Note that references/frameworks.md contains examples that use LangGraph, so you need that library only if you follow those examples.

• Python, for scripts/coordination.py
• An agent runtime that supports SKILL.md skills
• No API keys or accounts are needed by the files shown

Safety notes: scripts and network

This skill runs scripts: the helper file is Python and the agent may execute code that uses it. It does not use the network, according to the assessment for this item. Review scripts/coordination.py before running it, as you would any code from outside your project.

The helper is an illustrative sketch, not a hardened library. Test any multi-agent system thoroughly before production use. The skill itself states that hosted infrastructure and sandbox design belong to other skills, so do not expect it to cover those.

• Read scripts/coordination.py before executing it
• Test thoroughly; the helper code is not production-hardened
• Use other skills for hosted sandboxes, warm pools and task-model fit

Tips for getting useful results

Start with a single-agent baseline and measure it. The skill recommends this because multi-agent systems can use far more tokens and may not perform better. Give the agent your real task split so it can judge whether subtasks are truly parallel or independent.

Ask for the trade-offs in writing. The most useful answers name the pattern, the failure modes and the cost. Treat model selection as part of the design, since the skill notes that better models often help more than larger token budgets.

• Measure a single-agent baseline before adding agents
• Describe whether subtasks are parallel, sequential or dependent
• Ask for failure handling and error cascade prevention explicitly
• Consider model quality alongside architecture