hermes-skill-router
A Hermes Agent plugin that takes the always-on skill catalog out of every Chat Completions request
and appends a short list of the skills that fit the turn. The model keeps skills_list and
skill_view, so it can still list or open any skill.
The skill list is embedded once and cached, so a warm turn routes in about a second.
The intent of this plugin is to provide a fundamental feature in everyday agentic use. In
particular, it is for people who keep one super-agent profile that does everything but do not want
the context polluted by so many skills that the model struggles to pick the right one. Even for
specialist profiles, the number of specific skills can grow quickly. A skill router for a
super-agent also pairs well with a memory provider like
Hindsight, which takes care of memory routing and turns
raw history into organized memory that can be distilled into more skills when needed.
This plugin is not a replacement for periodic maintenance of your skill library, such as folding
related skills into references for a top-level skill. But it is easier for the model to pick a skill
when it is fresh in context and relevant.
Every setting, both endpoint protocols, the display record and the measurements are in
technical-documentation.md.

How it works
Hermes dumps the whole skill catalog into the model context. This plugin hides the catalog and only
surfaces skill suggestions when they fit the task. You can also pin a list of eager skills that
appears under Pinned skills: in the router block.
The embeddings endpoint compares your newest message, together with the typed
messages before it (up to 10,000 characters), with the skill rows and keeps a cosine order. A BM25
term index built beside the vector index scores the same text by the prompt's exact words, and a
read-only association store adds skills that were loaded for similar prompts before. The plugin
fuses those three orders with reciprocal rank fusion, gives candidates a small capped recency bump
when their skill path resolves, and cuts the result to the shortlist. The rerank endpoint then
scores that shortlist against the same query, and the plugin suggests what scores at or above
cutoff.
If a service is down or too slow, the plugin falls back to the ordinary skill catalog once per
compaction window, so a bad endpoint costs latency, not a broken turn, and the catalog never
reaches the model twice in the same window.
Historical learning (associations)
The router learns which skills you loaded for similar prompts. The association channel decays
each load with a 30-day half-life and surfaces skills with support of three or more for the
current prompt's terms. A separate recency bump counts a skill once per session turn and fades
it with a 14-day half-life, moving it up at most five shortlist positions. A missing database
means the channel is off with one warning and the other two channels still route.
To seed it from your history, let one routed turn write the index at cachePath, then run:
python3 -m hermes_skill_router.associations --catalog ~/.cache/hermes-skill-router/index.json
That reads ~/.hermes/state.db read-only and writes
~/.cache/hermes-skill-router/associations.db. The --catalog file is the index at cachePath,
which defaults to ~/.cache/hermes-skill-router/index.json; pass your configured path when you
changed it. The command exits 1 with cannot read catalog when that file is absent. Add
--max-sessions N for a bounded scan. The command is idempotent, so re-running it adds nothing.
The backfill is the only writer: a routed turn opens the store read-only, so rerun the command
after a batch of work whose loads you want the channel to learn from.
Pre-reranking
Three channels propose a fused shortlist (size 50), then the reranker scores it:
- Cosine: the newest message plus up to 10,000 characters of preceding context, embedded
and compared by vector similarity. - BM25: the same query text scored by exact words (
k1 1.2,b 0.75) over the catalog
text the embedder sees. - Associations: skills with decayed usage for the prompt's terms, as above.
Reciprocal rank fusion (constant 20, weights 1.0, 0.5, 1.0) merges the three orders, a
recency bump moves a skill up at most 5 positions, then the cut to 50 happens. Only then
does the reranker run. fusionMode: cosine skips the term index, the store, and the bump
and returns the cosine order alone; shadow computes the fused order and logs it while
still returning cosine.
Install
-
Install the plugin.
hermes plugins install <owner>/hermes-skill-routerFor development, link the checkout instead:
ln -sfn /path/to/hermes-skill-router ~/.hermes/plugins/hermes-skill-router -
Enable it.
hermes plugins enable hermes-skill-router -
Point the plugin at an embedder and a reranker in the profile config:
plugins: entries: hermes-skill-router: settings: embedBaseUrl: http://127.0.0.1:8012 rerankBaseUrl: http://127.0.0.1:8010 -
Run both services. This repository ships an embeddings server for BGE-M3 on CPU:
HSR_MODEL_DIR=/path/to/bge-m3 HSR_PORT=8012 python3 -m service.embed_serverIt serves
POST /v1/embeddingsandGET /healthon127.0.0.1:8012. No reranker is bundled, so
pointrerankBaseUrlat any service that answers the rerank protocol in the technical
documentation. Both base URLs must be bare origins.
default-models.md covers the two default models, how to download them, and
three ways to serve the embedder and the reranker. -
Check both health routes, then run one turn and read its dump:
curl -s 127.0.0.1:8012/health curl -s 127.0.0.1:8010/health HERMES_DUMP_REQUESTS=1 hermes -z "draft a git commit message for a bug fix"The newest dump under
~/.hermes/sessions/carries no## Skillsheading, and its last message
starts withSkills routed for this request. When no block appears, the plugin log carries one
warning naming the reason, or, for a completed pass that selected nothing, the decision line.
Recommended setup
The defaults are what we run, so you only have to set the two base URLs:
- Embeddings: BGE-M3 on CPU, served by the bundled
service.embed_serveron 8012, with
embedModelId: bge-m3. - Rerank:
tasksource-decider-nanothrough a Cohere-compatible rerank service on 8010, with
rerankProvider: cohere. - Routing:
cutoff: 0.01,shortlistSize: 50,maxSuggestions: 10,fusionMode: livewith all
three channels on, and the 6000, 20000 and 30000 ms timeouts. Keep them unless your endpoints need
different budgets.
Use
A routed turn ends with one extra system message. The sample below carries suggestion rows first,
then the pinned rows:
Suggestions:
- <suggested name>: <description>
path: <absolute path to the skill's SKILL.md>
- <suggested name with no description>
path: <absolute path>
Pinned skills:
- <eager name>: <description>
path: <absolute path>
Every suggestion and pinned row carries its name, its description and the path the host's skill lookup
resolved, which is the file skill_view opens. Suggestions are best first, capped at
maxSuggestions, where 0 means no cap. Pinned rows appear in the block of a request whose messages
carry no earlier router block, which is what opens a compaction window; a request whose messages carry
an earlier block carries the suggestions only, and a request whose earlier block a compaction removed
lists the pinned rows again. Rows that deferredSkills leaves listed stay under an Also listed:
marker on every turn and are never suggested. The model can open any row with skill_view, and
skills_list still lists the whole catalog. When the shortlist misses, it can search by hand:
skill_router_search takes any query in the model's own words and returns ranked names,
descriptions and skill paths.
The last decision also appears on screen, and neither place costs a token. The desktop app gets a
Skills routed pane on the right rail, collapsed by default, with the names and one caption line. In
hermes --tui, run /skills-routed to dock the widget, which reads the same record and shows the
same names. Both show their caption only for a routed record. The record holds names only and never
request text.
Configuration
Settings live under plugins.entries.hermes-skill-router.settings in the profile config. These are
the ones most setups touch:
| Option | Default | Meaning |
|---|---|---|
enabled | true | Master switch. False leaves every request untouched. |
embedBaseUrl | http://127.0.0.1:8012 | Embeddings endpoint root. |
embedModelId | bge-m3 | Model name sent to the embeddings endpoint. |
rerankBaseUrl | http://127.0.0.1:8010 | Rerank endpoint root. |
rerankModel | tasksource-decider-nano | Model name sent to the rerank endpoint. |
eagerSkills | empty | Skills listed under Pinned skills: in the router block, with their read paths, and never suggested. |
maxSuggestions | 10 | Cap on suggested rows, from 0 to 50. 0 means unlimited. |
Every other key, with its bound and its effect, is in the
configuration reference.
Documentation
- technical-documentation.md covers routing end to end, the request
rewrite, the suggestion record schema, both display protocols, every setting, both endpoint
protocols, failure behaviour, the measured effect and the tests. - default-models.md covers the default embedder and reranker models, how to
download them, how to serve each one, how to check the endpoints answer, and what the plugin does
when an endpoint is down. - LICENSE is the MIT license.
README from the reviewed commit 5345ce9; it updates when the author re-pins.
mortang2410