---
title: "Auto"
description: "Intent-classified router, the front door to OrchestKit and the DEFAULT entry point for any goal-shaped request. Classifies a plain-English goal and routes it to the right specialist skill. Routing is never overhead, so use it even when the target skill seems obvious; skip only when already executing inside another skill (no recursion). Triggers on: auto, do this, figure out, just make, I want, help me, fix, build, improve, any goal description."
canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/auto"
---

# Auto

Intent-classified router, the front door to OrchestKit and the DEFAULT entry point for any goal-shaped request. Classifies a plain-English goal and routes it to the right specialist skill. Routing is never overhead, so use it even when the target skill seems obvious; skip only when already executing inside another skill (no recursion). Triggers on: auto, do this, figure out, just make, I want, help me, fix, build, improve, any goal description.

<span className="badge badge-blue">Command</span> <span className="badge badge-yellow">medium</span>

```bash title="Invoke"
/ork:auto
```

<ContextualSkillSidebar slug="auto" />

> **Auto** Intent-classified router, the front door to OrchestKit and the DEFAULT entry point for any goal-shaped request. Classifies a plain-English goal and routes it to the right specialist skill. Routing is never overhead, so use it even when the target skill seems obvious; skip only when already executing inside another skill (no recursion).


# auto: Intent Router

The front door to OrchestKit. **You describe a goal in plain English; the router classifies it and hands off to the right specialist.** One entry point, many execution paths.

> **Why this exists:** OrchestKit has 107 skills, but usage telemetry shows users fire only the handful they can name by memory (10 distinct skills across thousands of sessions). The dominant cause of "dead" skills is **no front door**, not low quality. This router turns "you must know the exact `/ork:<name>`" into "describe what you want."

**Core principle:** routing is a *deterministic workflow*, not an autonomous agent (Anthropic, *Building Effective Agents*). Classify → confirm → hand off. The router never does the work itself, it picks who does.

## When to use

**By default, for any goal-shaped request.** An unambiguous goal is a 1-step
route: auto classifies, confirms in one line, and hands off, no extra hops,
so there is no "too obvious for auto".

| Use `auto` for… | Skip only when… |
|---|---|
| Any goal description ("fix X", "get Y to Z") | Already executing inside another skill (no recursion) |
| The right skill isn't obvious | Chaining a known multi-skill workflow you're mid-way through |
| You think you know the skill, auto confirms & short-circuits | |

> **Design note (2026-07-12):** this table previously said "Go direct when you
> already know the skill / the request maps unambiguously to one". That inverted
> instruction made the front door structurally unreachable, a competent model
> always believes it knows the target, so the router recorded near-zero
> invocations across thousands of sessions (the exact dead-skill problem the
> "Why this exists" note above describes). Routers must be framed as the
> default path, not an escape hatch for confusion.

## Intent categories → OrchestKit skill

| intent | signal words | routes to |
|---|---|---|
| **fix** | fix, debug, broken, failing, error, crash, regression | `fix-issue` |
| **diagnose** | why, why isn't, why does, why can't, investigate | `fix-issue` (investigation-first) |
| **optimize** | faster, reduce, latency, bundle, minimize, below N ms | a **`/goal` optimization loop** (see Gaps) |
| **cover** | coverage, untested, get to N% | `cover --target N` |
| **design** | design, architect, how should we, explore, idea | `brainstorm` |
| **build** | build, implement, create, add feature, from ticket | `implement` |
| **review** | review, PR, MR, pull request, #N | `review-pr` |
| **verify** | verify, check, make sure, passes, green | `verify` |
| **improve-skill** | improve the skill, optimize the prompt, SKILL.md | the **holdout-promotion gate** (see Gaps) |
| **(fallback)** | no confident category | clarify with ONE question |

Full per-category parameter extraction + edge cases: `references/routing-rules.md`.

## Model weight (orthogonal second dimension)

Intent picks **who** does the work. Weight picks **how expensive that worker should be**. A route is `{intent} @ {weight}`. Weight never changes the intent and never replaces it. The taxonomy above and the 7 disambiguation rules are untouched by it.

Tiers are the ones already declared in `src/agents/*.md` frontmatter (`haiku` 3 · `sonnet` 23 · `opus` 6 · `inherit` 4). No parallel taxonomy.

| weight | tier | the task is… |
|---|---|---|
| **Light** | `haiku` | mechanical or IO-bound, single file, deterministic output, trivially revertible |
| **Standard** | `sonnet` | the default: bounded judgment, known pattern |
| **Heavy** | `opus` | adversarial, security, safety, architecture, cross-cutting, or ambiguous |

**Resolution is asymmetric:** ANY heavy signal ⇒ Heavy; Light requires ALL light signals; everything else is Standard. Under-powering a security review yields a confident wrong answer nobody catches; over-powering a rename only wastes money.

Weight is **per leg, not per route**. A PR review can be a Heavy security leg plus a Light lint leg. Full signal table, per-intent defaults, and the honest limits of this lever: `references/routing-rules.md`.

> **This is the selector, not the cap.** `src/hooks/src/pretool/task/team-size-gate.ts` is an ex-post, per-session counter keyed on `ORK_TEAM_OPUS_MAX` (default 8). Its default posture is advisory (`outputWarning`); with `ORK_TEAM_SIZE_HARD=1` it escalates to `outputDeny` and refuses the spawn outright. Either way it reads the model read-only: it can refuse a premium spawn, but it cannot *choose* a cheaper one for you. Routing is what chooses. The two compose, cap as backstop and routing as selector; never duplicate the cap's counting here.

## The flow

```
  CLASSIFY  ->  CONFIRM  ->  HAND OFF
     |            |             |
  intent       show the     invoke the
  + weight     route        target skill;
  one line     + nod        follow ITS phases
```

### 1. Classify

Name the route and the one signal that decided it in a single short line. Example: *"'get latency under 200ms' names a metric + a direction, so optimize, not fix."*

Apply the disambiguation rules (most specific wins; explicit verb beats inferred intent). **The load-bearing one: explicit verb wins**, "Fix the slow query" → `fix`, not `optimize`. For the full ordered ruleset (all 7, including the truly-ambiguous fallback), `references/routing-rules.md` is canonical.

Then classify **weight in the same pass**, naming the signal that decided it: *"touches auth and models an attacker → Heavy."* Intent first, weight second; a weight call never rewrites the intent you just committed to.

**A `route:` line is a prior, not a verdict.** When the prompt context carries one line of the shape `route: <class> -> /ork:<skill> (conf 0.xx)` or `route: <class> -> Agent(<name>) (conf 0.xx)`, it came from the Jev routing seam (`ORK_ROUTE_JEV=steer`, off by default, #4233): one typed judgment of the capability class, taken before you read this table. Treat it as the prior for this step, state in one sentence whether you agree and why, and then classify as above. Your reasoning still decides; a confident prior you disagree with is worth a sentence, never a silent override in either direction. The confirm step is unchanged; the hand-off tool follows the target: a `/ork:` skill goes through the Skill tool, an `Agent(...)` target through the Agent tool.

### 2. Confirm (low ceremony)

Show the chosen route in one line and get a nod before handing off:

```
Goal:   "{original goal}"
Intent: {category}
Weight: {Light|Standard|Heavy} ({tier}), decided by: {signal}
Route:  {skill or loop} {extracted args}
        [run] · [adjust] · [cancel]
```

For low-risk single-pass routes (`verify`, `review`), an inline "routing you to verify, ok?" is enough. Never hand off without a nod.

**Premium spend is never silent.** Routing down (Light/Standard) needs no approval, because spending less is not a decision the user has to make. Routing **up to Heavy** is premium spend and gets its own line the user must accept:

```
⚠️  Heavy route: {N} opus-tier leg(s), triggered by: {heavy signal}
    [approve premium] · [run Standard instead] · [cancel]
```

If they decline, run Standard and say plainly which check is weakened. Never upgrade mid-handoff or inside a spawned agent the user did not see.

### 3. Hand off

Invoke the target skill with the extracted parameters and **follow that skill's own phases and guardrails**, do not override them. The router's job ends at the handoff; the specialist owns execution and its own report.

**A hand-off is a Skill-tool invocation, not a recommendation.** The failure mode that motivated M170 (#3127): telemetry traced 43 router hand-offs and found ZERO reached an executor skill (`implement`, `cover`, `fix-issue`, `review-pr`), the route was named in chat, then the work happened inline in the main loop, so the executors' specialist wiring (implement → backend-system-architect, cover → test-generator) never activated. Therefore:

- Once the user nods, the SAME turn must contain the Skill-tool call for the routed skill. Never end the routing turn with only a description of what will run.
- Doing the routed work inline "because it's faster" is a routing failure, not a shortcut, the executor's parallel specialists and guardrails are the point of routing.
- If the routed skill genuinely cannot run (missing prerequisite, wrong repo state), say exactly that and stop; do not silently absorb the work into the main loop.

## Fallback + honest gaps

- **Fallback category.** If no category clears a confident threshold, ask exactly ONE clarifying question rather than guessing. A rising fallback rate is the leading indicator that the taxonomy needs work, surface it, don't bury it.
- **`optimize` has no dedicated skill (yet).** OrchestKit's metric-driven optimization runs as a **`/goal` loop** using the loop recipe library (`prd-to-goal` → `references/recipe-library.md`). Route `optimize` there and say so plainly, don't pretend a `experiment` skill exists.
- **`improve-skill` routes to the evolution gate.** Self-optimizing a `SKILL.md` goes through the champion/challenger **holdout-promotion gate** (`assess` evals + `evolution-engine`), not a one-shot edit. It requires a benchmark + holdout set first.

## Stacked invocation (CC 2.1.199+)

`/skill-a /skill-b <goal>` loads all leading skills (up to 5) into context at once; the trailing args belong to the whole stack. So `auto brainstorm <goal>` pre-loads the specialist alongside the router, useful when the user already knows part of the route. The router still owns classification and handoff; a pre-loaded specialist does not bypass the confirm step.

## Guardrails

- **No recursion.** `auto` must not route to itself, directly or via a spawned agent.
- **No bypass.** Routing does not skip the target skill's guardrails, readonly enforcement, or confirmation steps.
- **Classification quality is the whole job.** A misroute that fails silently is worse than a fallback question. When two categories are equally plausible, ask, don't gamble.
- **No silent upgrade.** A Heavy (opus/fable) leg is premium spend and requires an explicit nod on its own line. Downgrades stay silent.
- **The cap is not the router's to move.** Never read, set, or suggest raising `ORK_TEAM_OPUS_MAX`. That is the user's budget.
- **A gate denial is not a re-route trigger.** If `team-size-gate` denies a spawn, do NOT relabel a Heavy leg as Standard to slip under the cap. Report the denial and let the user decide.
- **Weight is a hint, not an override.** The router cannot change an agent's declared `model:`. It selects skills and agents, and sets the caller's model that the 4 `inherit` agents adopt. It never overrides a target skill's own agent selection.

## Validation

Routing accuracy is gateable, not vibes. `routing-benchmark.json` holds 50 labeled `goal → category` pairs (easy + genuinely ambiguous). Validate after any change to the category table or disambiguation rules:

```bash
# isolated classification check via the bare-eval harness
bare-eval   # grade router output against routing-benchmark.json
```

Target ≥95% category accuracy; track the fallback rate as a degradation alarm as the skill library grows.

## References

- `references/routing-rules.md`: per-category parameter extraction, edge cases, disambiguation
- `routing-benchmark.json`: 50 labeled goal→category pairs for accuracy validation

## Quality Bar

Done means all of these hold:
- Classification reasoning is stated out loud BEFORE a route is committed, naming the chosen intent category and the signal words that triggered it.
- Weight is classified in the same pass as intent, naming the signal that decided it, and resolves asymmetrically (ANY heavy signal ⇒ Heavy; Light needs ALL light signals; else Standard).
- The confirm block names one of the taxonomy's intent categories, its target skill or `/goal` loop, and the extracted args, on one line.
- Every Heavy (opus/fable) leg is surfaced for explicit approval before handoff; no premium spend is silent, and declining it runs Standard with the weakened check named.
- Adversarial, security, safety, architecture, and cross-cutting work is never routed below opus tier; mechanical single-file IO-bound work is not routed above haiku tier.
- The router neither counts spawns nor touches `ORK_TEAM_OPUS_MAX`, and never downgrades a Heavy leg to evade a `team-size-gate` denial.
- No target skill is invoked without an explicit nod (or `-y`); handoff never precedes confirmation.
- When two categories are equally plausible, exactly ONE clarifying question is asked, the fallback is never silently guessed.
- `optimize` routes to a `/goal` loop and `improve-skill` to the evolution gate; neither claims a dedicated skill that does not exist.
- The router does none of the target work itself and never routes to `auto` (no recursion).

## Related skills

- `help`: static categorized directory (browse, don't route)
- `prd-to-goal`: decompose a spec into a `/goal` line (the `optimize` route's engine)
- `fix-issue` · `cover` · `brainstorm` · `implement` · `review-pr` · `verify`, the route targets
- `assess`: champion/challenger holdout gate (the `improve-skill` route)


---

## References (1)

### Routing Rules

# Routing Rules

Per-category parameter extraction + edge cases. Read during the Classify step to configure the target skill correctly.

## fix → /ork:fix-issue

- **Extract:** bug description (full goal), target files if named, ticket/issue `#N`, quoted error message.
- **Invoke:** `/ork:fix-issue {description or #N}`
- **Edges:** "fix the tests" is `fix` (repair broken tests), not `cover` (add new tests). "fix performance" is ambiguous → ask: debug a specific issue, or optimize a metric?

## diagnose → /ork:fix-issue (investigation-first)

- A "why…" question is a gentler entry than a fix command. Frame the plan as **observe → hypothesize → propose**, then offer to apply the fix.
- **A "why…" question is ALWAYS `diagnose`, even when it names a failure** ("why isn't the build green", "why does the API return 500", "why can't users log in"). The **question form** is what makes it `diagnose`, without one, a statement of breakage or a repair imperative is `fix` ("there's a regression in checkout", "resolve the 500 errors on /api/users").
- **Invoke:** `/ork:fix-issue {question}` with an investigation framing. ("I'll investigate first, then propose a fix, ok?")

## optimize → /goal loop (no dedicated skill)

- **Extract:** metric (latency/throughput/bundle/memory), direction (minimize for size/time/cost; maximize for score/rate), goal value + unit, target files.
- **Invoke:** compose a `/goal` loop via `/ork:prd-to-goal` → `references/recipe-library.md`. Be explicit that this is a `/goal`-driven loop, not a `/ork:experiment` skill (which doesn't exist).
- **Edges:** "make it faster" with no metric → ask what to measure (response time? build time? bundle?). Multiple metrics → pick the emphasized one, note the rest as constraints.

## cover → /ork:cover

- **Extract:** target % ("90%" → 90, "above 85" → 85), scope ("the auth module" → `src/auth/`).
- **Invoke:** `/ork:cover --target {N}`
- **Edges:** "write more tests" with no target → ask the target %. "test the new feature" is `build`/`verify` (functional tests), not `cover` (coverage %). A surface called out as **"untested"** is `cover` even with no % target ("the payments service is untested, fix that"), the "fix" there repairs a coverage gap, not a bug; ask the target % at invoke time.

## design → /ork:brainstorm

- **Extract:** topic (full goal). Deep mode if the goal says "thorough/comprehensive/deep dive" or spans multiple systems.
- **Invoke:** `/ork:brainstorm {topic}`
- **Edges:** "how should we…" is `design`, not `build`. "Design AND build…" → start `design`, offer `build` after.

## build → /ork:implement

- **Extract:** feature description, ticket ID, mode (greenfield/brownfield/refactor/bugfix).
- **Invoke:** `/ork:implement {description}`
- **Edges:** "implement the design from the brainstorm" → check for recent brainstorm state first.

## review → /ork:review-pr

- **Extract:** PR/MR number (`#123` → 123), scope filter if named.
- **Invoke:** `/ork:review-pr {number or branch}`
- **Edges:** "review my code" with no PR → ask which PR/branch. "review the design" is `design`, not `review`.

## verify → /ork:verify

- **Extract:** checks (tests/lint/typecheck/all), scope.
- **Invoke:** `/ork:verify`
- **Edges:** "make sure it works" → all checks. "check tests pass" → tests-focused.

## improve-skill → holdout-promotion gate

- **Extract:** which `SKILL.md`, quality metric (else task-completion against test cases).
- **Invoke:** the champion/challenger **holdout-promotion gate** (`/ork:assess` evals + `evolution-engine`). Requires a benchmark + holdout set to exist first, if missing, help the user define 5-10 cases before looping.
- **Edges:** "optimize my prompt" (not a skill file) → route to `optimize` with the prompt as the target. **When the improvement target IS a skill or agent**, a SKILL.md, a named skill, an agent prompt, it is `improve-skill` regardless of the verb: "optimize the prompt for the security-auditor skill" and "make the brainstorm SKILL.md produce better ideas" are both `improve-skill`, not `optimize`/`design`.

## Model weight (second, orthogonal dimension)

Intent answers **who does the work**. Weight answers **how expensive that worker should be**. Both are decided in the same Classify pass. Weight never changes the intent, and intent never fixes the weight: a route is `{intent} @ {weight}`.

The tiers are the ones already declared in `src/agents/*.md` frontmatter. There is no separate router taxonomy and no new vocabulary to learn (36 agents):

| tier | count | representative agents |
|---|---|---|
| `haiku` | 3 | eval-runner, emulate-engineer, release-engineer |
| `sonnet` | 23 | debug-investigator, database-engineer, test-generator, ci-cd-engineer, git-operations-engineer, llm-integrator |
| `opus` | 6 | security-auditor, security-layer-auditor, ai-safety-auditor, system-design-reviewer, code-quality-reviewer, workflow-architect |
| `inherit` | 4 | backend-system-architect, frontend-ui-developer, infrastructure-architect, product-strategist (these adopt the caller's model) |

### The rubric (one pass, decidable)

Read the goal once against both signal columns:

| dimension | light signal | heavy signal |
|---|---|---|
| output shape | deterministic, checkable by a command | judgment call, no single correct answer |
| blast radius | one file or one service | cross-cutting, multi-module, public API or schema |
| adversary | none modelled | an attacker, a race, or a hostile reviewer is modelled |
| specification | fully specified in the goal itself | ambiguous, needs interpretation |
| work type | mechanical or IO-bound (fetch, run, format, move, tag, publish) | architecture, security, safety, protocol or contract design |
| reversibility | trivially revertible | migration, data loss, or prod-facing |

**Resolution is asymmetric on purpose:**

1. **ANY** heavy signal makes it **Heavy** (`opus` tier).
2. **Light** requires **ALL** light signals (`haiku` tier).
3. Everything else is **Standard** (`sonnet` tier). This is the default, and the correct answer for most work.

The asymmetry is not laziness. Under-powering a security review or a schema migration produces a confident wrong answer that nobody catches; over-powering a file rename only wastes money. Bias the rare direction toward the recoverable failure.

### Weight is per leg, not per route

A single route often fans out into legs of different weight. Classify the legs, not the headline. `/ork:review-pr` on a PR touching auth is a Heavy security leg (`security-auditor`, opus) plus a Standard quality leg plus a Light lint leg. Do not promote the whole route to Heavy because one leg is.

### Default weight per intent

Defaults, not verdicts. The rubric overrides any row here when the goal carries a heavy signal.

| intent | default | promote to Heavy when | demote to Light when |
|---|---|---|---|
| fix | Standard | the bug is a security or data-integrity defect | a one-line, single-file, already-diagnosed repair |
| diagnose | Standard | root cause spans services or is adversarial | reading a log or reproducing a named error |
| optimize | Standard | the optimization changes architecture | tuning one measured constant |
| cover | Standard | tests must model an attacker or a race | mechanical test scaffolding for existing pure functions |
| design | Standard | architecture, protocol, or cross-cutting design | never (design is judgment by definition) |
| build | Standard | new public API, schema, or auth surface | single-file change fully specified in the goal |
| review | Standard | security, auth, crypto, or safety in scope | style or formatting only |
| verify | Standard | verifying a security-critical claim | running the existing checks and reporting the result |
| improve-skill | Standard | rewriting the evaluation contract itself | executing an existing benchmark (`eval-runner`, haiku) |

### Premium spend needs explicit consent

Routing **down** is silent. Spending less is never a decision the user has to approve.

Routing **up to Heavy** is premium spend (`opus` / `fable`) and MUST be surfaced in the confirm line, naming the heavy signal that triggered it. Never upgrade silently, never mid-handoff, never inside a spawned agent that the user did not see. If the user declines the upgrade, run Standard and state plainly which check is being weakened.

### Composition with the spend cap (they are different mechanisms)

```
routing        (ex ante,  per leg)     -> SELECTS the tier
team-size-gate (ex post,  per session) -> COUNTS what was selected, caps it
```

`src/hooks/src/pretool/task/team-size-gate.ts` is a **backstop, not a selector**. It reads `toolInput.model` exactly once, read-only, to classify premium vs non-premium, then increments a session ledger and warns or denies past `ORK_TEAM_OPUS_MAX` (default 8). It has no model-override surface and is ADVISORY by default, so its "Use sonnet/haiku" message is advice to a human that it cannot itself enact. Routing is what enacts it.

Rules that keep the two composed rather than duplicated:

- The router never reads, sets, or suggests raising `ORK_TEAM_OPUS_MAX`. The cap is the user's budget, not a router variable.
- A gate denial is **not** a re-route trigger. Do not relabel a Heavy leg as Standard to slip under the cap. Report the denial and let the user choose.
- The router does not re-implement counting. It has no session ledger and makes no claim about remaining budget.

### Honest limits of this dimension

Tier is bound **statically to agent identity** in each agent's frontmatter, and the spawn happens downstream in whichever skill the router handed off to. The router therefore has exactly two levers, and neither is a model override:

1. **Selection**: which skill and which agent gets the work (choosing `eval-runner` over a sonnet agent is a real tier decision).
2. **The caller's model**: the 4 `inherit` agents (11% of the catalog) adopt it, so the weight the router hands off at propagates to that bloc.

Everything else is a documented hint carried into the handoff. Per the no-bypass guardrail, the router does not override a target skill's own agent selection.

## Disambiguation (when multiple categories match)

1. Explicit verb wins. "Fix the slow query" → `fix`.
2. Metric + direction → `optimize`.
3. Percentage in a test context → `cover`.
4. Question form → `design` ("how should") or `diagnose` ("why"), and this beats symptom words: "why isn't the build green" is `diagnose`, not `fix`.
5. PR/MR/`#N` → `review`.
6. Ticket reference → `build`.
7. Truly ambiguous → ask ONE question naming the two candidate routes. **Do not guess when two DIFFERENT skills are plausible and the goal names no artifact, metric, or number.** Canonical fallbacks: "fix performance on the dashboard" (fix vs optimize), "review my code" with no PR/branch named (review vs verify), "test the new feature" (cover vs verify vs build), "the queries are slow and maybe vulnerable to injection" (optimize vs review).