# Parallel Fanout

> Decompose a task into 2+ truly independent sub-tasks and dispatch them concurrently via separate `task()` calls. Pick whether to fan out explicitly, not by accident. USE WHEN: the user task is clearly decomposable into 2+ independent sub-tasks (independent files, independent probes, independent analyses), you would otherwise serialize work that has no real dependency, user said "in parallel" / "并行" / "fan out" / "spawn agents" / "同时跑". TRIGGER PHRASES: "in parallel", "parallel", "fan out", "spawn agents", "并行", "同时", "concurrent", "subagents", "multi-agent", "同时跑几个". SKIP WHEN: sub-tasks have a hard data dependency (output of A is input of B), the user explicitly said "sequential" / "one at a time", there is only one sub-task.

- Skill: `minimax-ai/parallel-fanout` (Agent Skill)
- Install (CLI): `npx skillmds@latest add minimax-ai/parallel-fanout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/minimax-ai/parallel-fanout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: MiniMax AI (https://skillmd.com/u/minimax-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/minimax-ai/parallel-fanout

---


# Parallel Fanout

When the user task is clearly decomposable into 2+ **truly independent** sub-tasks, the
agent has two choices:

1. **Serialize**: do them one by one, holding the conversation hostage.
2. **Fan out**: dispatch them concurrently, aggregate the results.

This Skill is about **knowing when to choose (2)** and **how to dispatch + aggregate
cleanly** so the user gets the parallel speedup without losing correctness.

## mcode 0.2.4 surface

Each sub-task is a separate `task()` call:

```text
task(
  description:    string,            // 3-5 word label, required
  prompt:         string,            // the brief, required
  agent_name:  "explore" | "worker" | "verifier",  // required
  run_in_background?: boolean        // optional; usually false for fan-out
)
```

The agent dispatches all the calls in a single response; mcode executes them
concurrently subject to the host's per-session buffer-unordered limit (8 by
default in 0.2.4; check the runtime config if unsure). The agent then waits
for all to complete before aggregating.

`agent_name` is the canonical mcode spelling. `agent_name=` is accepted as
a runtime alias but the Skills prefer canonical. `mavis` is the root agent
not a sub-agent; do not pass it as `agent_name`.

## When to use

Activate when **any** of these is true:

- The user task is clearly decomposable into 2+ independent sub-tasks.
- The sub-tasks touch **independent files / directories / systems** (so there is no
  shared state to corrupt).
- The user explicitly said "in parallel" / "并行" / "fan out" / "同时".
- You would otherwise serialize work that has no real dependency.

## When NOT to use

- The sub-tasks have a **hard data dependency** (output of A is the input of B).
- The user explicitly said "sequential" / "one at a time" / "按顺序".
- There is only one sub-task (no fan-out to do).
- The sub-tasks would all touch the same file (race condition risk).

## Process

1. **Decompose explicitly**. Write the list of sub-tasks in the brief header before
   dispatching anything. "Sub-tasks: A, B, C" is the single most important line.
2. **For each sub-task, decide context size** (see `fork-context-decision` Skill):
   - Self-contained sub-task? `none` (just the brief in `prompt`).
   - Needs prior context? `N` or `all` → inline the prior content into `prompt`.
3. **Check mcode's per-session buffer-unordered limit**. Default in 0.2.4 is 8
   concurrent `task` calls. If you have more sub-tasks, the host will queue or
   fail — split the batch or use `run_in_background: true` and poll
   `task_output` later.
4. **Dispatch the batch** in a single response. mcode runs them concurrently
   subject to the buffer-unordered limit.
5. **Wait for all to complete**. The aggregator MUST verify each sub-task's
   output before declaring success (use `completion-audit`).
6. **Surface the parallelism in the user-facing message**. "I dispatched 3
   sub-agents in parallel; here are their results." The user should know
   fan-out actually happened (vs serial).

## Output contract

After activating this Skill, the agent's next message MUST include:

- The **list of sub-tasks** dispatched (one per `task` call).
- The **chosen context level** per sub-task.
- The **aggregation** result (per-sub-task outcome + overall verdict).
- A **completion audit** step (each sub-task verified).

## Common pitfalls

- **Fanning out for the sake of it** — parallelism is a tool, not a goal. If two
  sub-tasks are easier to do serially, do them serially.
- **Missing the data dependency** — the most common bug. Always check: does
  sub-task B actually need sub-task A's output? If yes, serialize.
- **Hitting mcode's buffer-unordered limit silently** — the host will queue or
  fail. Check the limit first; if you have more than 8, run them in waves.
- **Aggregating without verification** — one sub-task may have silently failed.
  Always read each output.
- **Using `agent_name="mavis"`** — mavis is the root, not a sub-agent.
  Use `explore` / `worker` / `verifier`.
- **Writing the sub-task brief in a separate `brief=` field** — mcode 0.2.4
  has no `brief` field. The brief goes in `prompt`.

## Example

The example below is **MiniMax Code 0.2.4 `task` tool syntax**. The fan-out
is 3 sub-tasks, all `none` context, all dispatched in one response, mcode
runs them concurrently.

```text
# Sub-tasks: A, B, C
# Concurrency cap: 8 (mcode 0.2.4 default)
# Context level: none (all sub-tasks are self-contained)
# Aggregation: read each output, run completion-audit, then summarize

> task(
    description="Look up X in repo 1",
    agent_name="explore",
    prompt="""
      Task name: lookup-X-repo1
      Task:     Find every file in <repo1> that imports `X`.
      Return:   List of <repo1>/<path> files, one per line.
    """
  )

> task(
    description="Look up Y in repo 2",
    agent_name="explore",
    prompt="""
      Task name: lookup-Y-repo2
      Task:     Find every file in <repo2> that imports `Y`.
      Return:   List of <repo2>/<path> files, one per line.
    """
  )

> task(
    description="Look up Z in repo 3",
    agent_name="explore",
    prompt="""
      Task name: lookup-Z-repo3
      Task:     Find every file in <repo3> that imports `Z`.
      Return:   List of <repo3>/<path> files, one per line.
    """
  )

# (Agent waits for all three.)
# Aggregator reads each output, audits per `completion-audit`.
```

The **decision** (3 sub-tasks, `none` context, wait-for-all) is the same; the
**call shape** is what mcode 0.2.4 actually exposes.

## Verification checklist

- [ ] Did you write the sub-task list in the brief header before dispatching?
- [ ] Did you stay under mcode's per-session buffer-unordered limit (default 8)?
- [ ] Did you choose the right context level per sub-task (via `fork-context-decision`)?
- [ ] Did you wait for all sub-tasks to complete before aggregating?
- [ ] Did you verify each sub-task's output (via `completion-audit`)?
- [ ] Did you use `agent_name` from `{explore, worker, verifier}` (not `mavis`)?
- [ ] Did you put the sub-task brief in the `prompt` field (not a separate `brief`)?