Claude Skill

multi-agent-orchestration

Designs and runs systems where several AI agents cooperate. Use whenever the user wants to split a task across agents, design planner and worker roles, define message contracts between agents, add a reviewer or critic loop, handle agent failures, or evaluate a multi-agent setup a

LLM Mart · 0 points · 0 views 49 listing impressions 0 install-command copies
Download mehranqadirian-skills-agent-engineering_multi-agent-orchestration-c88187d.zip · 10 KB

Install

skills CLI npx skills add https://github.com/MehranQadirian/skills/tree/main/agent-engineering/multi-agent-orchestration
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
Git git clone https://github.com/MehranQadirian/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.

README

multi-agent-orchestration

A Claude skill for designing and running systems where several AI agents cooperate.

What it does

  • Picks a coordination pattern: orchestrator-worker, pipeline, fan-out, critic loop or debate
  • Defines roles, message contracts and shared state
  • Adds limits, retries and validation against injection between agents
  • Evaluates the setup against a single-agent baseline
  • Ships a runnable orchestrator skeleton and a dependency free contract validator
  • Includes templates for contracts and role cards

Try it

Design a planner and worker setup that summarizes 50 PDFs.

Add a reviewer agent that checks the draft against criteria.

Is a multi-agent design worth it for this task?

Install

Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.

Claude Code:

cp -r agent-engineering/multi-agent-orchestration ~/.claude/skills/

Structure

multi-agent-orchestration/
├── SKILL.md                         skill instructions for Claude
├── scripts/
│   ├── orchestrator_skeleton.py     runnable orchestrator with retries, budget and trace
│   └── validate_contract.py         JSON schema check for agent outputs
├── references/
│   ├── patterns.md                  patterns, roles, contracts, security
│   └── evaluation.md                baselines, metrics, launch checklist
└── templates/
    ├── contract.json                handoff message template
    └── agent-role.md                role card

Skill manifest

multi-agent-orchestration

Split a complex task across specialized agents, coordinate them through explicit contracts, and verify the combined result. Use multiple agents only when a single agent cannot do the job reliably.

multi-agent-orchestration/
├── SKILL.md
├── scripts/
│   ├── orchestrator_skeleton.py   runnable orchestrator: retries, budget, timeout, trace, gap report
│   └── validate_contract.py       dependency free JSON schema check for agent outputs
├── references/
│   ├── patterns.md                pattern decision guide, role design, contracts, security
│   └── evaluation.md              baselines, test set, metrics, trace analysis, launch checklist
└── templates/
    ├── contract.json              handoff message with schema, limits and tools
    └── agent-role.md              role card to fill before writing prompts

When to use

  • The task has independent parts that can run in parallel
  • Different parts need different tools, prompts or permissions
  • A second agent should review or challenge the first agent's output
  • Context is too large for one agent

If none of these is true, use one agent. Say so to the user.

Choose a pattern

Pattern Description Best for
Orchestrator-Worker One planner delegates to workers and merges results Research, code changes across files
Pipeline Output of agent A feeds agent B Extract, transform, validate
Fan-out / Fan-in Many workers run in parallel, one aggregator merges Batch analysis
Critic loop Producer and reviewer iterate until criteria pass Writing, code review
Debate Agents argue positions, a judge decides Ambiguous decisions

Decision guide and risks per pattern: references/patterns.md.

Design steps

  1. Define the goal and measurable success criteria
  2. List roles; fill a role card (templates/agent-role.md) per agent with one responsibility and minimal tools
  3. Define message contracts (templates/contract.json)
  4. Decide shared state: what is passed, what stays private
  5. Add limits: max steps, max tokens, timeouts, retry policy
  6. Add verification: an independent check before returning results
  7. Log every handoff for tracing and debugging
  8. Evaluate against a single-agent baseline (references/evaluation.md)

Example contract

{
  "task_id": "T-104",
  "role": "researcher",
  "input": {"question": "Summarize the report", "files": ["report.pdf"]},
  "output_schema": {
    "summary": "string",
    "sources": ["string"],
    "confidence": "low|medium|high"
  }
}

Validate any agent output:

python3 scripts/validate_contract.py schema.json output.json

The schema language is tiny: "string", "number", "boolean", "low|medium|high" for enums, ["string"] for arrays, nested objects, and a trailing ? for optional keys.

Reference orchestrator

Run the offline demo to see retries, budget and trace in action:

python3 scripts/orchestrator_skeleton.py

Core shape (see the script for the full version with locks and timeouts):

orch = Orchestrator(call_model)          # call_model(role, payload) -> dict
result = orch.run("summarize the report")
# {"result": "...", "gaps": [...], "steps": 8}

Replace call_model with your real model or tool runner. Keep the schemas in SCHEMAS in sync with your prompts.

Failure handling

  • Validate every agent output against its schema; retry once with the error message
  • Use timeouts and a global step budget to prevent loops
  • On repeated failure, return partial results with an explicit gap report
  • Never let one agent's output act as instructions for another without validation (prompt injection risk)
  • Separate agents that read untrusted content from agents that hold powerful tools

Evaluation

  • Compare against a single-agent baseline; keep multi-agent only if it wins on quality or cost
  • Track success rate, schema validity, retries, latency and token cost from trace.jsonl
  • Keep a fixed test set and rerun it after every prompt or topology change

What to report back

Field Content
Chosen pattern and why a single agent was not enough
Roles one line each, with tools
Contracts schema per handoff
Limits steps, timeout, retries
Evaluation plan baseline, test set size, metrics
Known risks injection, cost, single points of failure

Related skills

  • systematic-debugging: trace handoff logs to find which agent produced a wrong result
  • pdf-processing: a worker agent for document extraction and verification
Files (skills)
  • references
    • evaluation.md 2.4 KB
      Loading…
    • patterns.md 3.2 KB
      Loading…
  • scripts
    • orchestrator_skeleton.py 5.3 KB
      Loading…
    • validate_contract.py 3.2 KB
      Loading…
  • templates
    • agent-role.md 722 B
      Loading…
    • contract.json 421 B
      Loading…
  • README.md 1.6 KB
    # multi-agent-orchestration
    
    A [Claude skill](../../README.md) for designing and running systems where several AI agents cooperate.
    
    ## What it does
    
    - Picks a coordination pattern: orchestrator-worker, pipeline, fan-out, critic loop or debate
    - Defines roles, message contracts and shared state
    - Adds limits, retries and validation against injection between agents
    - Evaluates the setup against a single-agent baseline
    - Ships a runnable orchestrator skeleton and a dependency free contract validator
    - Includes templates for contracts and role cards
    
    ## Try it
    
    > Design a planner and worker setup that summarizes 50 PDFs.
    
    > Add a reviewer agent that checks the draft against criteria.
    
    > Is a multi-agent design worth it for this task?
    
    ## Install
    
    **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload.
    
    **Claude Code:**
    
    ```bash
    cp -r agent-engineering/multi-agent-orchestration ~/.claude/skills/
    ```
    
    ## Structure
    
    ```
    multi-agent-orchestration/
    ├── SKILL.md                         skill instructions for Claude
    ├── scripts/
    │   ├── orchestrator_skeleton.py     runnable orchestrator with retries, budget and trace
    │   └── validate_contract.py         JSON schema check for agent outputs
    ├── references/
    │   ├── patterns.md                  patterns, roles, contracts, security
    │   └── evaluation.md                baselines, metrics, launch checklist
    └── templates/
        ├── contract.json                handoff message template
        └── agent-role.md                role card
    ```
    
  • SKILL.md 5 KB
    ---
    name: multi-agent-orchestration
    description: Designs and runs systems where several AI agents cooperate. Use whenever the user wants to split a task across agents, design planner and worker roles, define message contracts between agents, add a reviewer or critic loop, handle agent failures, or evaluate a multi-agent setup against a single agent, even if they only say "use multiple agents for this". Covers coordination patterns, retries, limits and evaluation.
    ---
    
    # multi-agent-orchestration
    
    Split a complex task across specialized agents, coordinate them through explicit contracts, and verify the combined result. Use multiple agents only when a single agent cannot do the job reliably.
    
    ```
    multi-agent-orchestration/
    ├── SKILL.md
    ├── scripts/
    │   ├── orchestrator_skeleton.py   runnable orchestrator: retries, budget, timeout, trace, gap report
    │   └── validate_contract.py       dependency free JSON schema check for agent outputs
    ├── references/
    │   ├── patterns.md                pattern decision guide, role design, contracts, security
    │   └── evaluation.md              baselines, test set, metrics, trace analysis, launch checklist
    └── templates/
        ├── contract.json              handoff message with schema, limits and tools
        └── agent-role.md              role card to fill before writing prompts
    ```
    
    ## When to use
    
    - The task has independent parts that can run in parallel
    - Different parts need different tools, prompts or permissions
    - A second agent should review or challenge the first agent's output
    - Context is too large for one agent
    
    If none of these is true, use one agent. Say so to the user.
    
    ## Choose a pattern
    
    | Pattern | Description | Best for |
    |---------|-------------|----------|
    | Orchestrator-Worker | One planner delegates to workers and merges results | Research, code changes across files |
    | Pipeline | Output of agent A feeds agent B | Extract, transform, validate |
    | Fan-out / Fan-in | Many workers run in parallel, one aggregator merges | Batch analysis |
    | Critic loop | Producer and reviewer iterate until criteria pass | Writing, code review |
    | Debate | Agents argue positions, a judge decides | Ambiguous decisions |
    
    Decision guide and risks per pattern: `references/patterns.md`.
    
    ## Design steps
    
    1. Define the goal and measurable success criteria
    2. List roles; fill a role card (`templates/agent-role.md`) per agent with one responsibility and minimal tools
    3. Define message contracts (`templates/contract.json`)
    4. Decide shared state: what is passed, what stays private
    5. Add limits: max steps, max tokens, timeouts, retry policy
    6. Add verification: an independent check before returning results
    7. Log every handoff for tracing and debugging
    8. Evaluate against a single-agent baseline (`references/evaluation.md`)
    
    ## Example contract
    
    ```json
    {
      "task_id": "T-104",
      "role": "researcher",
      "input": {"question": "Summarize the report", "files": ["report.pdf"]},
      "output_schema": {
        "summary": "string",
        "sources": ["string"],
        "confidence": "low|medium|high"
      }
    }
    ```
    
    Validate any agent output:
    
    ```bash
    python3 scripts/validate_contract.py schema.json output.json
    ```
    
    The schema language is tiny: `"string"`, `"number"`, `"boolean"`, `"low|medium|high"` for enums, `["string"]` for arrays, nested objects, and a trailing `?` for optional keys.
    
    ## Reference orchestrator
    
    Run the offline demo to see retries, budget and trace in action:
    
    ```bash
    python3 scripts/orchestrator_skeleton.py
    ```
    
    Core shape (see the script for the full version with locks and timeouts):
    
    ```python
    orch = Orchestrator(call_model)          # call_model(role, payload) -> dict
    result = orch.run("summarize the report")
    # {"result": "...", "gaps": [...], "steps": 8}
    ```
    
    Replace `call_model` with your real model or tool runner. Keep the schemas in `SCHEMAS` in sync with your prompts.
    
    ## Failure handling
    
    - Validate every agent output against its schema; retry once with the error message
    - Use timeouts and a global step budget to prevent loops
    - On repeated failure, return partial results with an explicit gap report
    - Never let one agent's output act as instructions for another without validation (prompt injection risk)
    - Separate agents that read untrusted content from agents that hold powerful tools
    
    ## Evaluation
    
    - Compare against a single-agent baseline; keep multi-agent only if it wins on quality or cost
    - Track success rate, schema validity, retries, latency and token cost from `trace.jsonl`
    - Keep a fixed test set and rerun it after every prompt or topology change
    
    ## What to report back
    
    | Field | Content |
    |-------|---------|
    | Chosen pattern | and why a single agent was not enough |
    | Roles | one line each, with tools |
    | Contracts | schema per handoff |
    | Limits | steps, timeout, retries |
    | Evaluation plan | baseline, test set size, metrics |
    | Known risks | injection, cost, single points of failure |
    
    ## Related skills
    
    - `systematic-debugging`: trace handoff logs to find which agent produced a wrong result
    - `pdf-processing`: a worker agent for document extraction and verification
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.