model-pyramid

Pick model and effort for the session and for every subagent you spawn, then say so in one line each. This skill recommends and reports — it never spawns agents, edits configs, or blocks you.

Everything numeric here is dated (stamp: metadata.model_baseline). Any point version (e.g. 5.1, 5.5) or a silent weight swap under the same name ⇒ re-verify defaults, thinking, pairing and what it touched; a new model generation ⇒ full re-sweep, your evals included.

The two axes (use these, not a rule table)

• Claude had the context, tried — at higher effort too — and still got it wrong → capability gap → change the MODEL.
• Claude got it wrong by skipping a file, not running tests, not double-checking → thoroughness gap → change the EFFORT.

Effort is the main thinking-depth control — and more: it governs all response tokens (text, tool calls, thinking) — how many files get read, how much gets verified, how far a task runs before checking in. Lower effort ⇒ fewer tool calls.

⛔ The corollary that kills the most common mistake: search / exploration / repeated tool calling is the last place to economise on effort. Cutting effort on a search agent buys an agent that stops looking. Hold it or raise it (not to xhigh by reflex — see below).

Defaults: start here, move on evidence

1. Model — subagents inherit the session model; that is the correct default. Override only for a reason you can name.
2. Effort — set it explicitly. Omitted on the API = that model's default: Opus 5.5 medium; Fable 5.1, Opus 5, Sonnet 5 high; Haiku 4.5 none. A bare Agent-tool call inherits the session's (references/runtime-knobs.md).
3. Adjust with evals, not vibes. Step down where quality holds, up where it doesn't. Carrying settings over from an earlier model generation ⇒ re-sweep, don't reuse.

Sizing a fan-out

Classify per task, never per batch. One spawn of five mixed tasks gets five decisions.

Clamps

• At most one knob per layer — one tier down or one effort step, not both.
• Two layers is the norm. A third layer, or a bottom-tier pick from a frontier session, needs a one-line justification in the report.
• No hard floor. low is a documented, legitimate subagent setting — justify it, don't ban it.
• An explicit user override wins verbatim. Advisory means advisory.

Before you emit xhigh or max

• Raise max_tokens — 64k is the documented start, 128k for long agentic turns (Opus 5.5 thinks more per turn; Fable 5.1 wants it large from high up). It caps thinking plus text.
• Check the level exists on that model — an unsupported level silently falls back to the highest supported level at or below it.
• Thinking is always on for Opus 5.5 / Fable 5.1 / Fable 5 — thinking:disabled or budget_tokens ⇒ 400 at any effort; lower effort instead. (Opus 5: 400 only at xhigh/max.)
• max is for genuinely frontier problems — elsewhere it adds cost for small gains. On Opus 5.5, reserve xhigh/max for a measured quality gain.

Cost levers that are not "pick a cheaper model"

• Advisor — a stronger model consulted only at decision points. Fits long multi-step tasks where most turns are routine but plan quality decides the outcome; adds little on short tasks. Legal for every model it attaches to; no pairing row (Opus 5.5 today) ⇒ no advisor until a test request with that pair succeeds. → references/orchestration.md
• opusplan — Opus in plan mode, Sonnet for execution: free when the task genuinely splits that way.
• Effort down-step — usually a bigger, safer lever than a model down-step: it degrades gracefully and applies per request.

The cache trap

Changing model or top-level effort invalidates the prompt cache. Hold one level per cached conversation — vary effort across workloads, or use per-message effort (beta), which keeps the cache on Opus 5.5 / Fable 5.1 / Opus 5.

Report

One line per agent:

<label>  model=<alias|id>  effort=<level>  rule=<peer|search|bulk|long-horizon|default|override>  [flags]

Flags worth emitting: inherited, justified:<reason>, override, max_tokens-raised, cache-hold, advisor:<model>, non-fork, degraded:<what the runtime could not express> (effort-not-expressible only if neither Workflow opts.effort nor agent-type effort: frontmatter is available). Each line carries its rule + flags, so it survives compaction.

Files

Mechanical check

node scripts/check_plan.mjs '{"agents":[{"label":"reviewer","model":"claude-opus-5-5","effort":"max"}]}'

Checks only table facts (levels, max_tokens, thinking, advisor pairing, cache, search/both-knobs cuts vs the session's resolved effort). Unknown models are reported (model-unknown: re-verify this skill), never passed; aliases get no model-specific verdict. Zero findings = nothing fired, not "verified"; whether your sizing is wise is not judged.