agentsop-query-routing
Enhancement-overlay SOP for query-type routing — sending a query to the right index / tool / engine *before* retrieving, not after. Activate when a calling agent owns a retrieval or answering surface that fronts more than one handler (a summary index, a vector index, a text-to-SQL engine, a tool) and the inbound queries differ in kind: "summarize this doc" vs "find the clause about X" vs "how many orders shipped in Q3". Encodes the one non- negotiable insight — **one retriever cannot serve all query types; route first, retrieve second** — plus the three router families (LLM/selector, embedding
npx skills add agentsope/SkillAlchemy --skill agentsop-query-routing --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Orchestrates query routing to the appropriate downstream handler (summary, vector, text-to-SQL, or tool) before retrieval, based on the query type. It enforces that a single retriever cannot serve all query types and partitions routing across specialized handlers.
How it works
- Activates when there are multiple indices/tools behind one entry point and inbound queries vary by kind.
- Requires building a table mapping query kinds to their correct handlers and primitives, then implementing one handler per type independently.
- Provides three router families (Keyword/Rule, Embedding/Semantic, LLM/Selector) and a fallback mechanism with a confidence threshold.
- The router is written to emit a destination identifier (or multiple) before any retrieval, with a default fallback path for uncertain cases.
- Includes logging of routing decisions (query_hash, chosen_handler, score, fell_back) for observability and debugging.
When to use it
- When a single endpoint fronts ≥2 different retrieval/answering handlers and queries differ in kind (lookup, summarize, compute, compare).
- When the system needs to route before retrieval rather than retrieving from all handlers and merging results.
- During PR reviews of a router/classifier/conditional-edge that selects a downstream handler from the query.
What it can touch
- It references downstream handlers like SummaryIndex, VectorStoreIndex, NL2SQL engines, and decomposition or query-engine substitutes as destinations.
- It describes using routing components such as RouterQueryEngine, SelectorPromptTemplate, LLMSingleSelector, Dify Question Classifier, LangGraph conditional edges.
- It suggests integration with the per-framework skills and cross-links to related components (llamaindex, agentsop-dify, agentsop-langgraph).
Caveats
- Routing adds an LLM hop or extra computation when using LLM/embedding-based selectors; a fallback path is recommended for uncertain queries.
- Requires explicit description/label for each destination to improve routing quality.
- Misroutes should be observable; logging is required to diagnose issues.
# Query-Type Routing · Enhancement Overlay > Third-person operating model for a coder agent that owns a multi-handler > answering surface. Audience is the LLM agent writing/reviewing the routing > code — not the end user. > **One sentence**: *A retriever is shaped by the query type it was built for; > a summary index, a vector index, and a text-to-SQL engine are not > interchangeable — so classify the query and route first, then retrieve.* This is an **ENHANCE overlay**. It distills the cross-framework *routing pattern* from three source skills. For the per-framework API, cross-link the base skill: `[[llamaindex]]` (`RouterQueryEngine`), `[[agentsop-dify]]` (Question Classifier node), `[[agentsop-langgraph]]` (conditional edges). --- ## 1. 何时激活 (Activation Rules) Activate when **any** of the following holds: 1. The system has **multiple indices / tools / engines** behind one entry point, and a query must be dispatched to exactly one (or a few) of them. 2. Inbound queries **differ in kind** — at least two of: *lookup* ("what does the contract say about termination"), *summarize* ("give me the gist of doc Y"), *compute/aggregate* ("how many tickets closed last week"), *compare* ("dif
- 1. 何时激活 (Activation Rules)
- 2. 核心心智模型 (Core Mental Model)
- Principle 1 — One retriever cannot serve all query types
- Principle 2 — Route first, retrieve second
- Principle 3 — A router is only as good as its destinations' descriptions
- 3. SOP 工作流 (Agentic Protocol)
- Stage 0 — Confirm routing is warranted
- Stage 1 — Enumerate the query types and their handlers
- Stage 2 — Build one handler per type, in isolation
- Stage 3 — Write the router (pick the cheapest sufficient family)
- Stage 4 — Add the fallback default (non-negotiable)
- 4. 操作模型 (Operation Models)
- OP-01 EnumerateQueryTypes
- OP-02 BuildPerTypeHandler
What does the agentsop-query-routing skill do?
Enhancement-overlay SOP for query-type routing — sending a query to the right index / tool / engine *before* retrieving, not after. Activate when a calling agent owns a retrieval or answering surface that fronts more than one handler (a summary index, a vector index, a text-to-SQL engine, a tool) and the inbound queries differ in kind: "summarize this doc" vs "find the clause about X" vs "how many orders shipped in Q3". Encodes the one non- negotiable insight — **one retriever cannot serve all query types; route first, retrieve second** — plus the three router families (LLM/selector, embedding
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-query-routing --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.