skill-router

skill-router

This is the single always-loaded interface skill for a large on-disk skill library. Do not enumerate or ingest the complete catalogue. Route internally from the user's ordinary task.

Mandatory protocol

1. Translate the task into a concise capability query.
2. Call skill_search.
3. Inspect the bounded candidates and score explanations.
4. Select the best eligible skill for the task.
5. Call skill_fetch with all identity fields returned by that search result:

{
  "skill_id": "selected-skill",
  "expected_revision": "sha256:...",
  "catalog_generation": "sha256:...",
  "context": "the capability query"
}

1. Load only the returned body and continue the original task.
2. Do not ask the user to choose a skill unless the underlying task itself is genuinely ambiguous and requires domain clarification.

Identity rule

A bare skill_id is not an immutable body identity. Treat the selected skill as:

(skill_id, skill_version, revision_id, catalog_generation)

Never omit expected_revision or catalog_generation in the consumer path. If fetch reports a revision or generation mismatch, repeat search against the current catalogue. Do not retry with an unpinned bare fetch.

Temporal rule

Once fetched, keep that exact revision for the current task. Do not silently hot-reload a newly published revision into an in-flight context. Refresh only through a new search and exact fetch.

Ranking interpretation

The active policy is tf.skillrouter.hybrid-lexical.v1. It combines:

• exact token tiers: keywords 3.0, name 2.0, description 1.0;
• FTS5 Porter-stemmed/prefix relevance weighted 0.6;
• bounded edit-distance fuzzy relevance weighted 0.35;
• a capped historical suggestion-to-fetch multiplier;
• lifecycle penalties;
• lexical skill_id tie-breaking.

It is deterministic and explainable. It does not use embeddings or a learned classifier.

Consumer boundary

Normal agent use is read-only with respect to the catalogue and skill files. Runtime telemetry is written separately. Registration, indexing, deprecation, archival, and publication are operator functions and must not be invoked from the normal per-task agent loop.