/route

Return the one skill that owns a request, the reason, and a confidence. Or return none — that is a real answer, not a failure. This skill routes and stops. It never performs the routed work.

Insight: a flat list of skill names in context is a catalog, not a router. The agent still has to guess, and it guesses from its own narrative of what it is doing — which is wrong exactly when the routing matters. Routing on the object being touched is more robust than routing on the activity, because the object survives a mistaken self-narrative and the activity does not.

The failure mode this exists to prevent: hand-rolling a discipline from first principles while the skill that owns it sits unused in the same repo. It happens because the request did not use the skill's vocabulary, so nothing matched, so the agent proceeded — producing a worse version of something already built and tested.

Modes

Inputs

Required: the request to route, in the caller's own words. Do not paraphrase it into skill vocabulary first — the paraphrase is where the routing error enters.

Optional: the object being touched (path, artifact, external system).

Non-goals. This skill does not invoke the routed skill, rank skills by quality, maintain the catalog, or create a skill when none matches. It does not route to skills outside skills/ — other corpora on the host are the caller's to manage. It does not chain: routing to rpi means routing to rpi, not pre-deciding what rpi will do next.

Procedure

Four layers, in order. Stop at the first that yields a single owner.

1. Object. Name the object the request touches: host × system × artifact ("this repo × git × branch history", "external service × credentials"). Match the object against skill effects in skills/catalog.json. An effect is a declared fact about what a skill touches, so it survives a wrong self-narrative.
2. Declared trigger. Match the request against the description trigger phrases in each skills/*/SKILL.md. Triggers are authored to be the words a caller actually says.
3. Capability. Match the request's verb against declared capabilities in the catalog.
4. Tier narrowing. If two or more skills survive, prefer by tier for the request's shape: judgment work → judgment, running an experiment → execution, choosing a shape → meta. If a tie survives this, set owner to none, list the tied skills as candidates, and say why they overlap — an unresolved tie is a catalog defect worth reporting, not a coin flip to hide.

The catalog is the declared surface; query it directly rather than recalling the skill list from memory.

# Candidate skills whose declared surface mentions a term (layers 1-3).
jq -r --arg t "account" '
  .skills[]
  | select(([.name, .description] + .effects + .capabilities | join(" ") | ascii_downcase)
           | contains($t | ascii_downcase))
  | "\(.name)\t\(.tier)\t\(.effects | join(","))"' skills/catalog.json

# What one skill declares it touches, before routing to it.
jq -r --arg s "validate" '
  .skills[] | select(.name == $s)
  | {tier, capabilities, effects}' skills/catalog.json

Bias: routing to a skill that turns out unnecessary costs one skill load. Routing to nothing when an owner existed costs a hand-rolled reimplementation and every defect it carries. When two readings are close, route.

Ceiling: at most 3 candidates are ever returned. A request matching more than three skills is under-specified — say so and ask one clarifying question rather than returning a menu.

Anti-patterns

Output

{
  "request": "make sure this actually works before I close it",
  "owner": "validate",
  "layer": "trigger",
  "reason": "declared trigger 'independently validate'; effect is fresh judgment over exact content",
  "runner_up": "test",
  "confidence": "high"
}

owner is one slug, or none. layer names which of the four fired.

Done when: the response names exactly one owner (or none), cites the layer that fired, and names the runner-up when one existed. A response with no layer is a guess wearing a routing decision's shape.

Checks

• The owner slug exists in skills/catalog.json.
• The cited layer actually fires — re-running the match reproduces it.
• No skill was invoked by this skill.
• none was returned rather than a forced match when no skill owned the request.

Provenance

• Catalog and declared surfaces: skills/catalog.json (repo root) and docs/SKILL-ROUTER.md (generated router).
• Object-before-activity rationale and the observed failure it prevents (§2.7): not on main; read it at git show 9872483bd:docs/research/gstack-teardown-2026-08-08.md (branch recover/gstack-clean-room).

Failure behavior

If the catalog is unreadable, report that and stop. Do not fall back to routing from memory of the skill list — a stale routing table sends work to a skill that may no longer own it, and the caller has no way to see that happened.