Purpose
/multi-agent:route resolves the role map through four layers: the bundled
defaults, ~/.claude/multi-agent.yaml, the team layer and
.claude/multi-agent.local.yaml. This skill shows what those layers resolve to
and writes one of them. All three consumer layers absent is a valid state: the
bundled defaults apply. Keys, values, layer paths and the fan-out guard are
defined in
${CLAUDE_PLUGIN_ROOT}/reference/config.md.
No argument means check. It installs nothing; the resolver needs only Bash,
awk and git.
check (read-only)
${CLAUDE_SKILL_DIR}/scripts/setup.sh check session=<alias>
Pass session=<alias> with the family in your own model ID (opus, sonnet,
haiku, fable); omit it when you cannot tell, and the map is resolved as
under a frontier session. The JSON is the one /multi-agent:route all prints.
Show:
- one line per role:
single <model> @ <effort>; fanout <model> @ <effort>, withinheritwritten asinherit: omit the model option, and the layer insourcefor each value; - the
layersrows (read, absent, skipped, or not applicable at a home or non-repository root) and every entry ofnotesas written; each note (a skipped layer, a rejected value, an ignored key) is a finding to report; - the personal-override row: PASS when
.claude/multi-agent.local.yamlis gitignored, else WARN with the recommended line.claude/**/*.local.*. Recommend the line; do not edit.gitignore; - each
WARN team:row: a retired team file (the config block indocs/conventions/multi-agent.md, or.claude/multi-agent.yaml) that the resolver no longer reads. Relay the row's next step as written.
It modifies nothing.
apply
Run
checkand show the map. This is the before state.Settle the layer with the user, recommendation first:
local(.claude/multi-agent.local.yaml): this checkout only, for this person. The default for a personal preference.team:docs/conventions/multi-agent.yaml(under the convention home the repository binds). Shared with everyone who clones the repository.user(~/.claude/multi-agent.yaml): every repository on this machine.
teamandlocalare refused at a home or non-repository root.Settle the keys. Ask only for what the user wants changed; each value comes from the table in
config.md. Pass every key to set as<key>=<value>, and<key>=to remove one from that layer. Existing keys in the layer are kept.Preview, writing nothing:
${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer <layer> <key>=<value> ...It prints the target path and a diff. It exits 1 without writing when the resolver would reject or ignore a key; relay the reason and return to step 3.
Show the diff and ask for an explicit yes. Write only on that yes:
${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer <layer> --write <key>=<value> ...It prints the path written and the keys it read back from the file.
Run
checkagain and show the after map beside the before one, naming each value that changed and the layer that now supplies it. The file is what the next/multi-agent:routerun reads; nothing about the running session changes. Forteam, offergit addand a commit and run each only when the user accepts.
The fan-out guard
With fanout.frontier_guard: true, the bundled value, a stage that runs more
than one agent never runs them on a frontier model: under a Fable
session, or a session the caller did not name, each fan-out variant that would
inherit or name a frontier model takes fanout.model (opus) instead. A
single synthesis or judge agent keeps the role's own model. The basis is
recorded beside the key in
${CLAUDE_PLUGIN_ROOT}/reference/defaults.yaml.
fanout.frontier_guard=false is an explicit opt-in to frontier fan-outs: every
parallel worker then runs on the session model, so a frontier session runs
every agent of the stage on the frontier model (rates:
Pricing: model pricing; usage:
Manage costs: Track your costs;
as of 2026-10-11, recheck when either page moves the section linked here).
Before writing it, say this and ask the user to confirm that specific key,
separately from the rest of the change. Recommend the narrowest layer that
covers what they mean: local for one checkout, user for one machine, team
only when the whole team has agreed.
What this skill does NOT do
- Edit
.gitignore,CLAUDE.mdorAGENTS.md. - Write a model ID. Only aliases are accepted, so the map stays portable across providers.
- Change a named agent's model or effort. An agent such as
implementation:implementerorimplementation:scoped-implementerowns its tier through its own frontmatter and whatever its dispatcher passes on the call; the role map governs genericagent()and Agent dispatches only. - Recheck a default against upstream. That is
/multi-agent:audit-defaults.
Next
/multi-agent:route all
Prints the map the next workflow reads from args.roles.
Gotchas
- A layer file is rewritten whole, so its comments are not kept; the preview says so when the file has any.
- An existing layer that does not parse stops
applywith the line and the reason. Fix or remove the file first; setup never overwrites content it could not read. - The first
teamwrite creates the YAML. A retired team file, which the resolver no longer reads, seeds its keys and stays as it was;checknames it until it is deleted. - Team and local layers resolve against the repository root of the working directory. Inside a second worktree, run from that worktree.