@skill-tools/router

Semantic skill selection middleware for Agent Skills. Uses embedding-based routing to select which skills to inject into an agent's context window from large skill catalogs. Zero external dependencies — built-in TF-IDF embeddings. 

npm install @skill-tools/router

Quick Start

import { SkillRouter } from 'skillrouter';

const router = new SkillRouter();

await router.indexSkills([
  { name: 'deploy-vercel', description: 'Deploy apps to Vercel...' },
  { name: 'run-tests', description: 'Execute test suites...' },
  { name: 'lint-code', description: 'Run ESLint or Biome...' },
]);

const results = await router.select('deploy my app');
// [{ skill: 'deploy-vercel', score: 0.87, metadata: {...} }]

API

SkillRouter

Main class. Constructor accepts optional SkillRouterOptions with embedding config.

indexSkills(skills)

Embed and store skill descriptions. Builds TF-IDF vocabulary from the corpus.

indexDirectory(dirPath)

Auto-discover and index SKILL.md files in a directory.

select(query, options?)

Find the top-K most relevant skills for a natural language query.

Option Default Description
topK 5 Number of results
threshold 0.0 Minimum cosine similarity score
boost — Skill names to boost by 1.2x
exclude — Skill names or wildcard patterns to exclude

detectConflicts(threshold?)

Find skills with highly similar descriptions that may conflict.

save() / load(snapshot)

Serialize/restore the full index as JSON. Useful for persistence.

SkillRouter.fromSnapshot(snapshot)

Static factory to restore from a serialized snapshot.

Embedding Providers

Provider Status Description
'local' Built-in TF-IDF + FNV-1a hash, 256 dimensions, zero dependencies
'custom' Supported Bring your own embedding function
'openai' Planned OpenAI embeddings API

Custom Provider

const router = new SkillRouter({
  embedding: {
    provider: 'custom',
    dimensions: 1536,
    embed: async (texts) => {
      // Call your embedding API here
      return texts.map(t => myEmbedFunction(t));
    },
  },
});

Architecture