Skills API

Skills are the public API for progressive capability disclosure in createSmartAgent(...). They are exported from the package root:

import {
  type Skill,
  type SkillPolicy,
  type SkillDisclosure,
  DEFAULT_SKILL_POLICY,
  SMALL_TIER_SKILL_POLICY,
} from "@cognipeer/agent-sdk";

Skill

type Skill = {
  key: string;
  title: string;
  header: string;
  prompt: string | (() => Promise<string> | string);
  needsSandbox?: boolean;
  minModelTier?: "small" | "large";
  isAvailable?: () => boolean | Promise<boolean>;
  listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
  bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
  rankToolHeaders?: (
    query: string,
    headers: SkillToolHeader[],
  ) => Promise<SkillToolHeader[]> | SkillToolHeader[];
  defaultBindNames?: string[];
};

Fields

Field	Purpose
key	Stable model-facing identifier, usually namespaced (builtin:pdf, integration:github, mcp:jira).
title	Human-readable title for operators and host UIs.
header	One-line description shown in <available_skills> before the skill is opened.
prompt	Extra operating instructions returned from open_skill. Use a function when the prompt depends on workspace state.
needsSandbox	Metadata returned by open_skill; host runtimes can use it to prepare a sandbox.
minModelTier	Hides "large" skills when skillPolicy.modelTier === "small".
isAvailable	Availability gate for connected integrations, feature flags, or credentials.
listToolIndex	Cheap list of tool names and descriptions. Used to decide whether a skill is small or large.
bindTools	Returns concrete ToolInterface objects. With no names, bind the whole small skill. With names, bind only that subset.
rankToolHeaders	Optional ranking hook for large skills when open_skill receives a query.
defaultBindNames	Deterministic fallback subset for large skills when the model opens without a usable query.

SkillToolHeader

type SkillToolHeader = {
  name: string;
  description?: string;
};

listToolIndex() should return headers, not full tool objects. Keep this list cheap and stable.

SkillPolicy

type SkillPolicy = {
  maxOpenSkills: number;
  maxBoundToolsPerSkill: number;
  maxBoundToolsTotal: number;
  modelTier?: "small" | "large";
  disclosure?: "catalog" | "search";
};

Policy controls how much capability the model can reveal during one invoke:

• maxOpenSkills: maximum distinct skill keys the model can open.
• maxBoundToolsPerSkill: maximum tools bound from one bind_skill_tools request or one small skill open.
• maxBoundToolsTotal: total skill-bound tool budget across the run.
• modelTier: controls minModelTier filtering.
• disclosure: how the model discovers the catalog. "catalog" (default) renders <available_skills> into the system prompt; "search" renders nothing and registers the search_skills tool instead, making prompt cost constant. See the Skills guide.

Defaults:

const DEFAULT_SKILL_POLICY = {
  maxOpenSkills: 4,
  maxBoundToolsPerSkill: 12,
  maxBoundToolsTotal: 40,
};

const SMALL_TIER_SKILL_POLICY = {
  maxOpenSkills: 1,
  maxBoundToolsPerSkill: 6,
  maxBoundToolsTotal: 18,
  modelTier: "small",
};

createSmartAgent options

const agent = createSmartAgent({
  model,
  skills,
  skillPolicy: DEFAULT_SKILL_POLICY,
});

When skills is non-empty, the smart runtime automatically:

• filters skills by isAvailable and skillPolicy.modelTier
• injects <available_skills> into the system prompt (catalog disclosure only)
• registers open_skill and bind_skill_tools, plus search_skills under search disclosure
• rebuilds the live runtime tool set after tools are bound
• keeps get_tool_response recovery variants from dropping bound skill tools

An empty skills array is a no-op and does not register the skill meta-tools.

Built-in meta-tools

open_skill

Schema:

{
  skillKey: string;
  query?: string;
}

Behavior:

• rejects unknown or unavailable skills
• enforces maxOpenSkills and maxBoundToolsTotal
• returns the skill prompt and needsSandbox metadata
• binds all tools for small skills
• returns a ranked toolIndex for large skills
• may bind defaultBindNames for large skills when no useful query is present

search_skills

Registered only under skillPolicy.disclosure === "search".

Schema:

{
  query?: string;
  limit?: number;
}

Behavior:

• resolves availability and model-tier gating at call time, not at prompt time
• ranks the catalog against query over key, title and header (see searchSkills)
• returns { skills: [{ skillKey, title, header, alreadyOpen? }], total, hint }
• lists the head of the catalog when query is omitted, or when nothing matches literally (a lexical ranker cannot bridge languages; the model reading the headers can)
• defaults limit to 10 and caps it at 25

Under this mode its description is the only place the model learns that skills exist, so keep any promptHooks.toolDescriptions override explicit.

bind_skill_tools

Schema:

{
  skillKey: string;
  toolNames: string[];
}

Behavior:

• requires open_skill to have been called for the skill
• caps toolNames to maxBoundToolsPerSkill
• appends newly bound tools by name, deduped against existing skill tools
• updates the live runtime tool set for later model turns in the same invoke

Low-level helpers

These helpers are exported for tests and advanced integrations:

Export	Purpose
createSkillRegistryRef()	Creates the per-invoke mutable registry used by the meta-tools.
createSkillTools(deps)	Creates the meta-tools against a registry (search_skills included under search disclosure).
createOpenSkillTool(deps)	Creates only the opener meta-tool.
createBindSkillToolsTool(deps)	Creates only the binder meta-tool.
createSearchSkillsTool(deps)	Creates only the search meta-tool.
resolveAvailableSkills(skills, opts)	Applies availability and model-tier filtering.
buildSkillHeaderBlock(skills)	Builds the <available_skills> system prompt block.
searchSkills(skills, query, limit)	Pure, deterministic ranking of a catalog against a task description.
appendBoundTools(ref, tools, policy)	Append-only, name-deduped registry mutation with total cap.
composeToolSets(input)	Rebuilds tool arrays with and without get_tool_response.
canOpenSkill(ref, policy)	Checks open/budget precedence before opening a distinct skill.
dedupeToolsByName(tools)	Keeps the first tool for each name.

Most applications should only use Skill, SkillPolicy, and createSmartAgent({ skills }). Use low-level helpers when you are testing skill catalogs or building a custom smart-runtime wrapper.