Agent Skills: Model Routing

Model Routing

Claude model choice is the biggest cost lever in Claude Code. Match the model to the work.

Decision matrix

| Task type | Model | Why | |---|---|---| | Long-horizon autonomous run (overnight build, large migration end-to-end) | Fable | Sustains multi-hour agentic work and async subagent fleets that stall lesser models | | Hardest unsolved problem (Opus failed or would need many retries) | Fable | Highest reasoning ceiling; one Fable pass can beat several Opus retries | | Architecture decision | Opus | Multi-step reasoning; hidden-cost detection | | Root-cause debugging (hard) | Opus | Hypothesis trees, multi-source evidence | | Security review | Opus | Risk sensitivity; knowledge of OWASP/CWE | | Feature implementation | Sonnet | Standard generation; good reasoning | | Code review (routine PR) | Sonnet | Fast; catches most issues | | Test writing | Sonnet | Pattern-based | | Research / docs lookup | Haiku | Fast; cheap; sufficient for retrieval | | Bulk file edits (rename, reformat) | Haiku | Mechanical work | | Dependency audit | Haiku | Running commands, parsing output | | Simple Q&A | Haiku | One-shot factual answers |

Cost table (approximate, check cc_docs_model_recommend for current)

| Model | Alias / ID | Input $/M | Output $/M | Relative | |---|---|---|---|---| | Fable 5 | fable / claude-fable-5 | $10 | $50 | 3.3× | | Opus 4.8 | opus / claude-opus-4-8 | $5 | $25 | 1.7× | | Sonnet 5 | sonnet / claude-sonnet-5 | $3 | $15 | 1× | | Haiku 4.5 | haiku / claude-haiku-4-5-20251001 | $1 | $5 | 0.33× |

Output tokens are the dominant cost in most Claude Code sessions. Two caveats on Fable 5: its new tokenizer produces ~30% more tokens for the same content (so the effective gap vs Opus is wider than the per-token price), and turns run longer. Use it where the capability ceiling matters, not as a default. Sonnet 5 uses the same new tokenizer (~30% more tokens than Sonnet 4.6 for identical content) and launched with introductory pricing ($2/$10 per MTok through 2026-08-31) — the table shows the sticker price.

Aliases auto-resolve to the latest generation — prefer fable/opus/sonnet/haiku over pinned IDs so a model refresh doesn't strand your config. Use opusplan for Opus-reasoning + Sonnet-execution, or best for "most capable available". Extended 1M-token context: opus[1m] / sonnet[1m] (Fable 5 is 1M by default; claude-fable-5[1m] is the long-context ID form).

Fast mode (/fast in-session, --fast at launch) keeps you on Opus (4.6/4.7/4.8) but optimizes for faster output — it does not downgrade to a smaller model. Toggle it when you want Opus-level reasoning without the usual latency. Not available on Fable 5.

Effort levels scale reasoning depth independently of model: low · medium · high · xhigh · max (Opus 4.7/4.8, Sonnet 5, and Fable 5 support xhigh). Set via /effort, --effort <level>, or effort: in skill/agent frontmatter — cheaper than jumping a model tier when you just need deeper thinking. On Fable 5 thinking is always on and effort is the only depth control — and even low effort on Fable often matches or beats max on prior models, so sweep downward for routine work.

Model cascading

The high-leverage pattern: start with a cheap model for planning, delegate implementation to cheap, reserve Opus for review gates.

| Phase | Model | |---|---| | Plan mode (Shift+Tab) | Opus (Fable for the hardest/longest-horizon plans) | | Implementation | Sonnet | | Subagent research | Haiku | | Code review gate | Opus | | Final sign-off | Opus | | Overnight / multi-hour autonomous run | Fable (orchestrator only; workers stay on Sonnet) |

Net effect: most tokens are on Sonnet/Haiku; Opus tokens are where they matter most; Fable tokens are reserved for the rare runs that justify the tier.

Budget planning

For a task estimated at N turns:

• Rough floor: 2k input + 2k output per turn = 4k tokens.
• Sonnet cost: 4k × $3/M = $0.012 per turn.
• 20-turn session on Sonnet: ~$0.24.
• Add 3 Opus review passes: +$0.45.
• Total: ~$0.70.

Use cc_docs_model_recommend(task, budget) to get a specific recommendation with cost projection.

Downgrade/upgrade triggers

Downgrade to Haiku when:

• Doing pure retrieval (grep results, file reads).
• Running a known command and parsing output.
• Rate-limited on Sonnet budget.

Upgrade to Opus when:

• Sonnet gets it wrong twice on the same subtask.
• Task is security-critical.
• Stakeholder cost of error is ≥ days of engineer time.
• You're designing something new (vs. implementing something known).

Upgrade to Fable when:

• Opus has failed (or would clearly need multiple retries) on the same problem.
• The run is long-horizon and autonomous — overnight builds, end-to-end migrations, multi-wave orchestration where mid-run drift is the failure mode.
• You're coordinating a fleet of long-lived async subagents and need the orchestrator to stay coherent for hours.
• Don't route security-scanning/offensive-security analysis to Fable — its cyber safety classifiers can refuse (refusal stop reason); keep that on Opus.

/plan mode

Shift+Tab toggles plan mode — uses Opus to think deeper without producing code. Use for:

• New feature scoping
• Debugging a tough bug before trying fixes
• Architecture choice before committing

Don't use plan mode for: known patterns, mechanical work, small tweaks.

MCP delegation

| Need | Tool | |---|---| | Model recommendation for a task | cc_docs_model_recommend(task, budget?) | | Compare two model choices | cc_docs_compare(["opus", "sonnet"]) | | Check cost of an autonomy profile | cc_kb_autonomy_profile(profile) |

Anti-patterns

• Defaulting to Opus everywhere → ~1.7× cost, rarely 1.7× value on routine work.
• Defaulting to Fable everywhere → 3.3× price and ~30% more tokens per task; the tier pays off only above Opus's ceiling.
• Haiku on hard tasks → gets it wrong, then you re-run on Opus = wasted double cost.
• Ignoring /plan on new work → code-first on unfamiliar problems wastes tokens.
• Not estimating budget → costs creep; you notice on the monthly bill.