Owner document for the role map the multi-agent skills resolve. The bundled
values live in defaults.yaml; a consumer layer overrides
them per key. How layers are found and ordered across the marketplace is the
config-cascade convention;
this page owns the keys.
| Layer | Path |
|---|---|
| Bundled | ${CLAUDE_PLUGIN_ROOT}/reference/defaults.yaml |
| User-global | ~/.claude/multi-agent.yaml |
| Team | <home>/multi-agent.yaml, <home> being the convention home the repository binds, else docs/conventions |
| Personal override | .claude/multi-agent.local.yaml (gitignored) |
Later layers win per key. Team and personal override are read only when the root is a
repository that is neither $HOME nor an ancestor of it
(lib/config-root.sh). The team file is validated by
schemas/multi-agent.schema.json. The
resolver no longer reads the old team locations, the config block in
docs/conventions/multi-agent.md and .claude/multi-agent.yaml;
/multi-agent:setup check names each one it finds. While the team YAML is
absent, the first /multi-agent:setup apply --layer team write copies the keys
of one of them, the block when there is one, into the new YAML and leaves the
old file in place. Every layer declares schema: 1; a layer that does not
parse or names another schema is skipped and named in notes, and the layers
around it still apply. The format is a YAML subset: nested mappings, scalars,
comments. No lists. /multi-agent:setup apply writes a layer after a preview
and an explicit yes.
| Key | Values | Bundled |
|---|---|---|
roles.<role>.model |
inherit, or an alias: opus, sonnet, haiku, fable |
per role |
roles.<role>.effort |
low, medium, high, xhigh, max |
per role |
workloads.<w> |
true declares workload <w>, false withdraws it; <w> holds only letters, digits, _ and -, and does not start with - |
code, research and mechanical declared |
roles.<role>.workloads.<w>.model / .effort |
as above; <w> is a declared workload |
worker.workloads.mechanical.model: sonnet (opt out with roles.worker.workloads.mechanical.model: inherit in any layer); a layer may set others, for example worker.workloads.mechanical.effort: low |
frontier |
comma-separated aliases treated as frontier | fable |
fanout.frontier_guard |
true, false |
true |
fanout.model |
an alias | opus |
verification, verification_skills.<skill> |
off, light, standard, strict |
light |
verification is not part of the role map. It sets whether /multi-agent:audit-defaults runs
its skeptic panel: light and off skip it and report every finding unverified, so no diff is
proposed. It is read from the team file at the default branch only, through
lib/read-verification.sh; the resolver ignores it in every layer, and the user-global and
personal files cannot set it. A skill entry beats the plugin value
(verification level).
Roles are orchestrator, worker, verifier and retrieval. A layer naming
another role or key is reported and ignored, and so is a workload no layer
declares. A declaration in any layer covers values set in every layer, so a
team layer can declare a workload that a personal override tunes. A full model id
(claude-opus-5-5) is rejected, so a role map stays portable across providers.
Whether a role may name haiku is decided in
routing-rubric.md; the resolver accepts it and adds a
note.
inherit means the calling workflow omits opts.model. For what an alias
resolves to per provider, see
model config: model aliases;
for the model an agent with no model runs on, see
workflows: cost.
For the values the subagent model field accepts, and the order in which a
subagent with no model resolves one, see
sub-agents: choose a model.
The effort values are the full set this resolver accepts; which of them a
spawn can use depends on the model it runs on. For each model's supported
levels, see
model config: adjust effort level.
pointer*, basis_*, claim_*, reason_*, as_of and recheck record
where each bundled default's basis lives. A role's basis_model and
basis_effort say whether an upstream statement sets that value (upstream,
with pointer_<field> and claim_<field>) or it is a judgment (judgment,
with reason_<field>); a workloads.<w>.<field> value records the same keys
on its role as basis_<w>_<field> and so on. The resolver prints the basis
beside each value, and a guarded fan-out model takes fanout.model's basis. They
are read from the bundled layer only, and /multi-agent:audit-defaults checks
each upstream pointer against its value.
Route a stage by how hard its work is, not by its topic. Mechanical work
(renames, formatting, one transformation applied at many sites, log filtering)
goes through the mechanical workload, which runs the worker on sonnet by
default. The hardest stage that one agent runs (a final synthesis, a judge, a
design decision) takes the role's single variant, which keeps the role's own
model. Everything else takes the role's default for its workload. The bundled
mechanical model is this repository's judgment, weighing the well-scoped coding row of
which Claude model should you build with: pick a model by task,
as of 2026-11-09; recheck when that row changes its starting model.
Role effort reaches workflow agent() calls, which pass opts.effort
explicitly, and Agent tool dispatches with no named type, which pass it as the
per-spawn effort parameter (route's Output section). A named agent runs at
its effort frontmatter unless its dispatcher passes effort on the call or
a source ranked above both applies. When it sets none, it runs at the session's
level on the main conversation's model; on another model that level does not
apply. route reads no settings file, so the
effort it prints is the level a caller asks for, before any cap. A loop lane's
level is its own lanes[].effort, not the orchestrator role.
- Pointer: sub-agents: choose an effort level, sub-agents: supported frontmatter fields and model config: effort level of subagents and teammates
maxEffortLevel is the consumer's hard cap over every role and every named
agent's pinned effort: any higher level, from a role, frontmatter or the
session, runs at the cap. Which settings scopes set it, how values across
scopes and a model's modelSettings entry combine, and how an organization
effort limit applies alongside it are read at the pointers below.
Every role resolves to two variants. single serves a stage that runs one
agent (a final synthesis or judge); fanout serves a stage that runs more than
one. With fanout.frontier_guard: true, a fan-out variant whose model would be
inherit under a frontier session, or under a session the caller did not name,
or that names a frontier alias, takes fanout.model instead. So the resolver
never emits a frontier session's own model for a fan-out stage. What the agent
runs on is the harness's call: see
sub-agents: choose a model and
run every subagent on one model.
Under an Opus session opus and inherit
name the same model, so the guard changes nothing there.
Setting fanout.frontier_guard: false is an explicit opt-in to frontier
fan-outs. Set it on the layer whose scope you mean: the personal override for one
checkout, the user-global file for every repository on one machine.
This docs/conventions/multi-agent.yaml raises the worker's effort and
declares a deep workload, which a caller selects with
/multi-agent:route worker deep. A consumer maps its own labels (an issue's
complexity, say) onto workloads in its own convention; the plugin ships no
such mapping.
schema: 1
workloads:
deep: true
roles:
worker:
effort: high
workloads:
deep:
model: opus
effort: xhigh
fanout:
frontier_guard: true