Register skills

Skills are Markdown playbooks (a deploy runbook, a debugging checklist) ranked in a separate corpus from tools, so a relevant skill is never crowded out by matching tools. The concept is covered in Tools, MCP servers & skills; Ratel's own coding-agent skills — including ratel-decompose-prompt, which extracts skills from a long system prompt — are on the Quick start.

Register a skill

A skill can declare the tools its instructions call: when the skill matches a query, those tools are pulled into the tools bucket (additively, deduped) so the agent gets the playbook and the tools it needs in one turn instead of a second search.

import {
  SkillCatalog,
  searchCapabilitiesTool,
  getSkillContentTool,
  type Skill,
} from "@ratel-ai/sdk";

const skills = new SkillCatalog();
skills.register({
  id: "vercel-deploy",
  name: "vercel-deploy",
  description: "How to deploy to Vercel: env vars, preview vs production, rollbacks.",
  tags: ["deploy", "ship to production"],     // indexed for ranking
  tools: ["vercel__deploy", "fs__read_file"], // surfaced alongside the skill when it matches
  metadata: { stacks: ["next", "vercel"] },   // non-indexed context for higher-layer ranking
  body: "## Deploying to Vercel\n1. ...",      // returned by getSkillContentTool
});

const search = searchCapabilitiesTool(catalog, skills); // 2nd arg → result gains a populated `skills` bucket
const load = getSkillContentTool(skills);               // id: "get_skill_content"

Only id, name, and description are required; tags, tools, metadata, and body are optional (parity with the Python SDK). Ranking indexes a skill's name, description, and tags; the body never enters the index, so a long playbook cannot drown out its own description.

How skills surface

Pass the SkillCatalog as the second argument to searchCapabilitiesTool and search returns the skills bucket alongside tools, each with its own result budget. The agent pulls a skill's full body into context on demand via getSkillContentTool (id get_skill_content, constant GET_SKILL_CONTENT_ID).

get_skill_content({ skillId }) returns { body }, or { error, isError: true } for an unknown id.

The SkillCatalog surface

SkillCatalog takes the same constructor options as ToolCatalog (SkillCatalogOptions = { trace?, method? }) and mirrors its surface:

skills.search(query, topK);   // → SkillHit[]  ({ skillId, score }); same (query, topK, origin?, method?) signature
skills.buildEmbeddings();     // same semantics as ToolCatalog.buildEmbeddings
skills.has(skillId);          // → boolean
skills.get(skillId);          // → Skill | undefined
skills.size();                // → number of registered skills
skills.invoke(skillId);       // → string: the Markdown body; throws on unknown id
skills.recordEvent(event);    // inject a trace event into the active sink
skills.drainTraceEvents();    // → unknown[]; memory sink only

invoke returns the body directly (body ?? ""), recording a skill_invoke trace event, and throws unknown skillId: <id> for an unknown id; getSkillContentTool is the boundary that translates that throw into the structured { error, isError: true } the agent sees.

Embeddings for skills

The skill corpus has its own embedding cache, maintained exactly like the tool one (Build the embedding cache): construct SkillCatalog with method: "semantic" or "hybrid" to embed eagerly at register, or keep the BM25 default and call skills.buildEmbeddings() before opting in per call. The two caches are independent — skills can rank hybrid while tools stay on BM25.

Embeddings cover the same projection the ranking indexes — name, description, tags — never the body, so a long playbook costs one small embedding. When the engines are worth it is on Semantic & hybrid search.

Next steps