Skill Discovery

How Vector-Based Discovery Works

Every skill registered in SkillRouter is embedded into a high-dimensional vector space using its name, description, and metadata. When your agent issues a discovery query, SkillRouter converts the query into the same vector space and performs an approximate nearest-neighbor search to find semantically similar skills.

This means your agents do not need to know exact skill names or identifiers. A query like "send a transactional email" will surface email-sending skills from providers like SendGrid, Resend, and Mailgun, ranked by how well they match the intent.

Using sr.discover(query)

The primary entry point for skill discovery is the sr.discover() method. Pass a natural-language query describing what you want to accomplish, and SkillRouter returns a ranked list of matching skills.

import SkillRouter from '@skillrouter/sdk';

const sr = new SkillRouter({ apiKey: process.env.SR_API_KEY });

// Basic discovery — returns top 5 matches by default
const results = await sr.discover("send a transactional email");

console.log(results);
// [
//   { id: "sendgrid-send-email", score: 0.94, provider: "SendGrid", ... },
//   { id: "resend-send-email",   score: 0.91, provider: "Resend",   ... },
//   { id: "mailgun-send",        score: 0.87, provider: "Mailgun",  ... },
// ]

Each result includes the skill metadata, a relevance score between 0 and 1, and the provider information. You can pass the top result directly to sr.execute() to run the skill immediately.

// Discover and execute in one flow
const [bestMatch] = await sr.discover("send a transactional email");

const result = await sr.execute(bestMatch.id, {
  to: "user@example.com",
  subject: "Welcome!",
  body: "<h1>Thanks for signing up</h1>",
});

Filtering by Category, Provider & Capability

You can narrow discovery results using filters. Filters are applied before the vector search, which reduces the candidate set and improves both speed and precision.

Category Filter

Restrict results to a specific skill category such as email, payments, storage, or web-browsing.

const results = await sr.discover("process a refund", {
  category: "payments",
});

Provider Filter

Limit results to skills from a specific provider. Useful when your organization has standardized on a particular service.

const results = await sr.discover("create a checkout session", {
  provider: "stripe",
});

Capability Filter

Filter by capability tags that describe what the skill can do, such as read, write, delete, or subscribe.

// Combine multiple filters
const results = await sr.discover("manage customer data", {
  category: "crm",
  provider: "hubspot",
  capabilities: ["read", "write"],
  limit: 10,
});

Relevance Scoring & Ranking

Discovery results are ranked by a composite relevance score that blends multiple signals. The final score is a weighted combination of:

You can override the default ranking by providing a custom scoring function:

const results = await sr.discover("upload a file to cloud storage", {
  rank: {
    semantic_similarity: 0.5,
    success_rate: 0.3,
    latency_score: 0.2,
    popularity: 0.0,  // ignore popularity
  },
});