| name | cost-routing |
| description | Top-level dispatcher that classifies every incoming request into scout / coder / architect tiers BEFORE any tool call. Routes Read, Grep, Glob, file-search, symbol-lookup, "where is X", and "list files matching Y" to haiku-scout. Routes known-location Edit, Write, multi-file refactor, test authoring, and bounded code changes to sonnet-coder. Reserves the main opus context for ambiguous design questions, ADRs, and tradeoff analysis. Use whenever a request lands in the main context and might involve file IO, code search, code edits, or design reasoning — which is almost every turn. |
Cost-Tier Routing
The main context runs on opus. Every Read, Grep, Glob, and Edit invoked at this tier bills at opus rates. Most operations don't need opus reasoning — they need a model that can run a command and report a result. This skill is the dispatch gate that stops opus from doing work haiku or sonnet would complete just as correctly for a fraction of the cost.
The three tiers
| Tier | Model | Owns | Example requests |
|---|
| scout | haiku | Read-only lookup, search, location | "Where is Foo defined?", "List files matching *.test.ts", "Count LOC in src/", "Read X and report Y" |
| coder | sonnet | Bounded code changes at known locations | "Add a test for parseDate", "Refactor auth.ts to use the new client", "Rename A → B repo-wide" |
| architect | opus | Ambiguous spec, tradeoff analysis, design | "Should we use Redux or Zustand?", "Draft an ADR for the auth rewrite", "Why is this architecture failing?" |
The dispatch decision (run this first, every turn)
Before reaching for any tool, run this classifier against the incoming request:
- Is the work entirely read / search / location? → scout. Dispatch
haiku-scout. Never call Read / Grep / Glob in the main context.
- Is the change scope AND the design already decided? → coder. Dispatch
sonnet-coder with a precise brief.
- Is the user asking "should we", "why", "what are the tradeoffs", "design X"? → architect. Stay in-context (you ARE opus) or dispatch with
model: "opus".
- Mixed? → split. Scout first to gather facts, then re-classify the next step. Never bundle scout work into an architect dispatch.
If the answer to #1 is yes and you find yourself reaching for Read / Grep / Glob in the main context anyway — STOP. That is the violation this skill exists to prevent.
Dispatch templates
See PROMPTS.md for the canonical brief for each tier. Use them verbatim — every field is load-bearing.
Worked examples
See EXAMPLES.md for ~15 classifications across the boundary cases (multi-file search, bug fixes with unknown root cause, "small" edits that hide design questions).
Enforcement
The companion PreToolUse hook (hooks/pre-tool-use-cost-check.sh) warns when Read / Grep / Glob fires in the main context. Register it in ~/.claude/settings.json (see EXAMPLES.md § Installing the hook).
- Default mode: warn (writes to stderr, the call proceeds).
COST_ROUTING_BLOCK=1 upgrades the warning to a hard deny — useful for sessions where you want zero tolerance.COST_ROUTING_BYPASS=1 silences the hook for legitimate one-shot inspection (a single Read of a file the user pasted a path to).
The hook cannot perfectly distinguish "top level opus" from "inside a subagent" — Claude Code does not currently expose that bit to hooks. It warns on every Read / Grep / Glob; you teach yourself to recognize the warning as "I'm probably in opus, should I have dispatched?"
When NOT to dispatch
- The entire task is one unattended CLI command (
gh pr view, docker ps). Use Bash directly — wrapping a one-shot command in an agent is pure overhead.
- The user pasted a single file path and asked for a single fact. Read it directly; dispatch overhead exceeds the saved tokens.
- The work is genuinely ambiguous design that needs opus reasoning. Don't dispatch yourself to yourself.
Common failure modes
- Tier creep — classifying a multi-file search as "design work" because it touches many files. Multi-file search is still scout.
- Dispatch without
model: — calling Agent with subagent_type: "general-purpose" and no model: parameter inherits the parent tier (opus → opus). Always pin the model.
- Skipping the classifier — jumping to Read on instinct. The classifier IS the skill; running it costs two seconds and saves the budget every time.
- Bundling tiers — handing scout work to a coder dispatch ("find the file, then edit it"). The coder agent will burn sonnet tokens doing scout work. Split: scout reports the path; coder edits at that path.
