Keys, layers and the fan-out guard are defined in
${CLAUDE_PLUGIN_ROOT}/reference/config.md;
read it when a note or a user question concerns a key, a layer or the guard.
Arguments
<role|all>: one of orchestrator, worker, verifier, retrieval, or
all for the whole map.
[workload]: optional, the second bare argument; applies the role's
workloads.<w> keys. The bundled layer declares code, research and
mechanical; a config layer may declare more (workloads.<w>: true).
session=<alias>: the session model's alias. When the caller did not pass
one, fill it from your own model ID: the family name in it (opus,
sonnet, haiku, fable) is the alias. When you cannot tell, omit it; the
resolver then treats the session as frontier, so fan-out stages name
fanout.model.
Run
${CLAUDE_SKILL_DIR}/scripts/route.sh $ARGUMENTS
Append session=<alias> when $ARGUMENTS carries none and you know your model
family.
Output
The JSON exactly as printed, in one fenced json block. Below it, one line per
role in this form:
<role>: single <model|inherit: omit the model option> @ <effort>; fanout <model|inherit: omit the model option> @ <effort> (basis: model <basis>, fanout model <basis>, effort <basis>)
Write inherit: omit the model option wherever a variant's omit_model is
true, so a caller copying the line passes no model and the agent runs on the
session model. Each <basis> is the role's basis entry as printed:
upstream (an upstream statement sets it), judgment (no upstream statement
does; the reason is in defaults.yaml), config (a consumer layer set it) or
unrecorded; the fanout model's basis is the guard's when guarded is true.
After the per-role lines, write this line as is:
Effort above maxEffortLevel runs at the cap; see reference/config.md "Hard cap".
Then list every entry of notes (a skipped layer, a rejected value, an ignored
key, a role that resolves to haiku) as written. A haiku note means the role
runs on a model no role here has passed the routing eval on; the rule is in
${CLAUDE_PLUGIN_ROOT}/reference/routing-rubric.md.
Exit 2 means an unknown role, workload or argument: relay the valid roles or
declared workloads from the error and stop.
A caller launching a workflow passes the JSON's roles object as
args.roles, unchanged. A caller spawning a subagent through the Agent tool
with no named type applies one variant to that call: it passes the variant's
model as model, or omits model when omit_model is true, and always
passes its effort as effort.
- Pointer: when a routed Agent dispatch runs at a different level than
the one passed, or you need the values the call accepts, fetch
sub-agents: choose an effort level,
sub-agents: choose a model
and model config: set the effort level
live.
- As of: 2026-10-31
- Recheck trigger: either sub-agents section changes which source wins
for a subagent's model or effort or when a family alias resolves to the
session's model, or the model-config section states
whether an effort cap limits the per-call
effort.
What this skill does NOT do
- Write any configuration layer. That is
/multi-agent:setup apply.
- Route a named agent. An agent dispatched by its own type, such as
implementation:implementer, implementation:scoped-implementer or
implementation:phase-verifier, owns its tier through its own frontmatter
and its dispatcher's rules. The map governs generic agent() calls and
Agent dispatches without a named type.
- Choose between a workflow and subagents. That is
/multi-agent:assess.
- Check the defaults against upstream. That is
/multi-agent:audit-defaults.
Next
/multi-agent:audit-defaults
Rechecks a default that looks wrong for the current models.
Gotchas
- Only aliases are accepted. A full model id in a layer is rejected and the
layer below supplies the key, because an alias resolves per provider and an
id does not.
fanout and single differ only under a frontier or unknown session. Under
an Opus session both say inherit, and opus would name the same model.
- The map never routes a named agent (
agentType, or an Agent dispatch by
subagent type), so the fan-out guard does not reach it on its own. Its
dispatcher may pass model or effort on the call; for which source wins
over the definition's pins, see the pointer record under Output. Keeping a
named agent such as scoped-implementer off a frontier session model is
that dispatcher's rule to keep.
- The route output never reflects
maxEffortLevel; the cap applies at run
time.
- The bundled defaults set only the
mechanical workload, which runs the
worker on sonnet; code keeps the role's model, and any other workload key
comes from a config layer. A caller that wants the session model for
mechanical work sets roles.worker.workloads.mechanical.model: inherit.
- Team and personal override layers resolve against the repository root of the working
directory. Inside a second worktree, run from that worktree.
1---2name: route3description: "Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value; fan-out stays off frontier models unless config opts in. Use when asked 'which model for the subagents', 'route the roles', 'what effort should the workers use', 'roles for the workflow args', 'model routing' or 'is fan-out on Fable', or before a skill launches a workflow that takes args.roles."4argument-hint: "<role|all> [workload] [session=<alias>]"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/route9 workflow-stage: session10 summary: Resolve model and effort per agent role for a multi-agent run11allowed-tools: ["Bash(${CLAUDE_SKILL_DIR}/scripts/route.sh:*)"]12shell: bash13---1415Keys, layers and the fan-out guard are defined in16[`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](${CLAUDE_PLUGIN_ROOT}/reference/config.md);17read it when a note or a user question concerns a key, a layer or the guard.1819## Arguments2021- `<role|all>`: one of `orchestrator`, `worker`, `verifier`, `retrieval`, or22 `all` for the whole map.23- `[workload]`: optional, the second bare argument; applies the role's24 `workloads.<w>` keys. The bundled layer declares `code`, `research` and25 `mechanical`; a config layer may declare more (`workloads.<w>: true`).26- `session=<alias>`: the session model's alias. When the caller did not pass27 one, fill it from your own model ID: the family name in it (`opus`,28 `sonnet`, `haiku`, `fable`) is the alias. When you cannot tell, omit it; the29 resolver then treats the session as frontier, so fan-out stages name30 `fanout.model`.3132## Run3334```bash35${CLAUDE_SKILL_DIR}/scripts/route.sh $ARGUMENTS36```3738Append `session=<alias>` when `$ARGUMENTS` carries none and you know your model39family.4041## Output4243The JSON exactly as printed, in one fenced `json` block. Below it, one line per44role in this form:4546```text47<role>: single <model|inherit: omit the model option> @ <effort>; fanout <model|inherit: omit the model option> @ <effort> (basis: model <basis>, fanout model <basis>, effort <basis>)48```4950Write `inherit: omit the model option` wherever a variant's `omit_model` is51true, so a caller copying the line passes no model and the agent runs on the52session model. Each `<basis>` is the role's `basis` entry as printed:53`upstream` (an upstream statement sets it), `judgment` (no upstream statement54does; the reason is in `defaults.yaml`), `config` (a consumer layer set it) or55`unrecorded`; the fanout model's basis is the guard's when `guarded` is true.56After the per-role lines, write this line as is:5758```text59Effort above maxEffortLevel runs at the cap; see reference/config.md "Hard cap".60```6162Then list every entry of `notes` (a skipped layer, a rejected value, an ignored63key, a role that resolves to haiku) as written. A haiku note means the role64runs on a model no role here has passed the routing eval on; the rule is in65[`${CLAUDE_PLUGIN_ROOT}/reference/routing-rubric.md`](${CLAUDE_PLUGIN_ROOT}/reference/routing-rubric.md).66Exit 2 means an unknown role, workload or argument: relay the valid roles or67declared workloads from the error and stop.6869A caller launching a workflow passes the JSON's `roles` object as70`args.roles`, unchanged. A caller spawning a subagent through the Agent tool71with no named type applies one variant to that call: it passes the variant's72model as `model`, or omits `model` when `omit_model` is true, and always73passes its effort as `effort`.7475- **Pointer**: when a routed Agent dispatch runs at a different level than76 the one passed, or you need the values the call accepts, fetch77 [sub-agents: choose an effort level](https://code.claude.com/docs/en/sub-agents#choose-an-effort-level),78 [sub-agents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model)79 and [model config: set the effort level](https://code.claude.com/docs/en/model-config#set-the-effort-level)80 live.81- **As of**: 2026-10-3182- **Recheck trigger**: either sub-agents section changes which source wins83 for a subagent's model or effort or when a family alias resolves to the84 session's model, or the model-config section states85 whether an effort cap limits the per-call `effort`.8687## What this skill does NOT do8889- Write any configuration layer. That is `/multi-agent:setup apply`.90- Route a named agent. An agent dispatched by its own type, such as91 `implementation:implementer`, `implementation:scoped-implementer` or92 `implementation:phase-verifier`, owns its tier through its own frontmatter93 and its dispatcher's rules. The map governs generic `agent()` calls and94 Agent dispatches without a named type.95- Choose between a workflow and subagents. That is `/multi-agent:assess`.96- Check the defaults against upstream. That is `/multi-agent:audit-defaults`.9798## Next99100/multi-agent:audit-defaults101Rechecks a default that looks wrong for the current models.102103## Gotchas104105- Only aliases are accepted. A full model id in a layer is rejected and the106 layer below supplies the key, because an alias resolves per provider and an107 id does not.108- `fanout` and `single` differ only under a frontier or unknown session. Under109 an Opus session both say `inherit`, and `opus` would name the same model.110- The map never routes a named agent (`agentType`, or an Agent dispatch by111 subagent type), so the fan-out guard does not reach it on its own. Its112 dispatcher may pass `model` or `effort` on the call; for which source wins113 over the definition's pins, see the pointer record under Output. Keeping a114 named agent such as `scoped-implementer` off a frontier session model is115 that dispatcher's rule to keep.116- The route output never reflects `maxEffortLevel`; the cap applies at run117 time.118- The bundled defaults set only the `mechanical` workload, which runs the119 worker on `sonnet`; `code` keeps the role's model, and any other workload key120 comes from a config layer. A caller that wants the session model for121 mechanical work sets `roles.worker.workloads.mechanical.model: inherit`.122- Team and personal override layers resolve against the repository root of the working123 directory. Inside a second worktree, run from that worktree.