Task router for AgentKit installs. Classifies the task, activates the right installed skills, chains them into the shortest workflow that fits, and spawns installed subagents at defined trigger points to raise output quality. Use at the start of multi-step, multi-domain, or ambiguous work, or when unsure which skill or agent applies.
Task router for AgentKit installs. Classifies the task, activates the right installed skills, chains them into the shortest workflow that fits, and spawns installed subagents at defined trigger points to raise output quality. Use at the start of multi-step, multi-domain, or ambiguous work, or when unsure which skill or agent applies.
user-invocable
true
when_to_use
Invoke at the start of multi-step or multi-domain work, when the right skill is unclear, when skills need sequencing into a workflow, or when deciding whether and when to spawn subagents.
Route any task to the right installed capability: the correct skill, the
shortest skill chain that fits, and the right subagents at the right moments.
This skill decides and dispatches — the routed skills and agents do the work.
Routing tables live with their owning skills. This skill adds the decision
protocol on top of them and duplicates none of their content. Output quality
comes from four levers this protocol controls: the right specialist per step,
fresh-context subagents for noisy or parallel work, verification steps matched
to risk, and refusing to orchestrate what a single skill does better.
Boundaries
Situation
Owner
Pick and sequence installed skills, time subagent spawns, in this session
this skill
Coordinate headless CLI jobs across runtimes, models, worktrees
the orchestrate skill (ak-orchestrate, engineer installs)
Run multi-session agent teams
the team skill (ak-team, engineer installs)
Discover or install skills you do not have yet
the find-skills skill (ak-find-skills, engineer installs)
Execute the domain work itself
the routed skill or agent owns execution
If the task is explicitly about running jobs headlessly, across CLIs, or in
parallel worktrees, hand off to the orchestrate skill now (when installed) and
stop.
The Protocol
Six steps. Steps 0-2 are cheap and mandatory; steps 3-5 scale with the task.
Step 0 — Proportionality gate (always run first)
Routing ceremony on a trivial task is itself a quality failure.
Condition
Action
User names a skill to use
Invoke that skill. Stop routing.
Single domain, single step, one obviously matching installed skill
Invoke it directly. Stop routing.
Pure conversation, opinion, or fact question
Answer. No skills, no agents.
Multi-step, multi-domain, ambiguous match, high risk, or no obvious skill
The class gives the default route shape; the modifiers bend it (bigger size
adds planning and delegation, higher risk adds verification, more domains add
domain-skill links).
Step 2 — Inventory what is actually installed
Never route to a capability that is not installed. Discovery is
runtime-native:
Claude Code: installed skills and their descriptions are listed in your
context (Skill tool); installed agents are the available subagent types
(Agent tool). Trust that list, not memory.
Codex: skills auto-discovered from ~/.agents/skills/ and the repo's
.agents/skills/; agents are agent_<slug> MCP tools when the
ak-codex-agent-runtime MCP server is registered, or TOML files under
~/.codex/agents/ / project .codex/agents/.
Capability missing? Use the find-skills skill (ak-find-skills) to discover
and install it when present; otherwise do the work inline and name the gap in
your final report. Do not silently pretend the capability exists.
Step 3 — Select and chain skills
Selection precedence:
Skill the user named.
Domain-specific skill over workflow-generic skill (a React feature routes
to the frontend skill first, then executes through the workflow skills).
One primary skill per distinct intent; secondary skills are follow-up
helpers, not co-owners.
Consult the owning routing references instead of guessing — and instead of
re-deriving what they already encode:
Decision
Load
Which domain skill fits this intent
../ak-find-skills/references/domain-routing.md (engineer installs; if absent, match installed skill descriptions)
Chain rules are in
references/chaining-patterns.md: the
understand → decide → execute → verify → deliver skeleton, entry/exit criteria
per link, artifact passing through report files, and the collapse rule that
keeps chains short.
Step 4 — Spawn subagents at trigger points
Subagents raise quality when they add a fresh context window, an enforced tool
boundary, parallel wall-clock, or a specialist system prompt — and lower it
when they fragment a task that needed full conversation context.
Load references/subagent-timing.md for the
trigger table (stage × condition → role), the delegation contract every spawn
must carry, parallel-safety rules, and the per-runtime dispatch dialect
(Claude Code Agent tool vs Codex agent_<slug> MCP tools).
Fast triggers you should never miss:
Investigation spanning more than two areas → parallel read-only explorer
agents at the start, not after you are lost.
Implementation finished → tester role before you claim done.
Ship, publish, or public-contract change ahead → reviewer role first.
Same failure twice → debugger role with the evidence so far.
Step 5 — Quality gates by risk
Verification is part of done, not optional polish:
Risk class
Mandatory before delivering
low (internal, reversible)
Executor skill's own checks
elevated (user-visible behavior, cross-module)
Test/verification link + self-review of the diff or draft
high (public contract, security, data, money, destructive, mass-audience send)
Verification link + independent reviewer role + explicit user confirmation before the irreversible step
Report outcome-first when the chain completes: what was delivered, which
links ran, which agents were used, what was verified, what gaps remain.
Worked Routes
Three compact examples of the protocol end-to-end:
"Fix the failing CI on this branch" — Step 0: single domain, obvious
owner. Route directly to /ak:fix. No chain, no agents unless /ak:fix
itself escalates. Total router overhead: one classification line.
"Add team billing with Stripe and a settings page" — class:
build-feature, size: epic, risk: high (money), domains: 3 (backend, payments,
frontend). Chain: scout → plan → implement (payment + frontend domain skills
under the workflow skill) → test → review. Agents: explorer roles scout
payment and settings code in parallel; implementer roles take disjoint file
sets per plan phase; tester after implementation; reviewer before ship (high
risk makes it mandatory).
"Launch a campaign for the new feature" (marketing install) — class:
plan-campaign, size: standard, domains: 2+. Chain per the marketing sequences
in chaining-patterns: research → persona/funnel → campaign brief → per-channel
content production → analytics setup. Agents: researcher roles in parallel at
the start; content-creator/copywriter roles per channel; content-reviewer role
before anything publishes (mass-audience send = high risk).
Anti-Patterns
Do not
Because
Spawn a subagent for a two-minute single-file edit
Delegation overhead exceeds the work; quality drops with context loss
Build a five-link chain for a single-domain ask
Every link adds handoff loss; the collapse rule exists for this
Route to a skill or agent you have not confirmed installed
Broken dispatch mid-task; inventory is Step 2 for a reason
Re-route mid-chain without new evidence
Thrash; reroute once per link on evidence, else surface to the user
Copy routing tables from owning references into prompts or docs
They drift; load them at decision time instead
Use this skill for headless cross-CLI or multi-worktree runs
That is the orchestrate skill's layer
Skip the reviewer role on high-risk work because the diff "looks clean"
The gate exists precisely for confident mistakes
Failure Handling
A link that fails does not advance the chain. Detour (fix or debug the
blocker, or rescope the link), then resume at the failed link. Two consecutive
failures on the same link: stop, report what was attempted, what failed, and
the smallest missing input — do not loop.
Subagent status handling: BLOCKED or NEEDS_CONTEXT means change the
context, scope, or approach before re-delegating. Never resend the same
failing prompt.
Handoffs
Work should run headlessly, across CLIs, or in parallel worktrees → the
orchestrate skill (ak-orchestrate, engineer installs).
Work needs multiple coordinated sessions → the team skill (ak-team,
engineer installs).
Needed capability is not installed → the find-skills skill
(ak-find-skills, engineer installs), else proceed inline and report the
gap.
