ai-sdk-skills

AI SDK tools for discovering and loading SKILL.md content from the open skills ecosystem.

What this package provides

• findSkillsTool: find and rank skill candidates (preconfig or search mode)
• readSkillTool: resolve and load a skill's SKILL.md into model-ready context

Install

pnpm add ai-sdk-skills ai zod

Quick start

import { generateText, stepCountIs } from 'ai';
import { initSkillsTools } from 'ai-sdk-skills';

const { tools } = initSkillsTools({
  find: {
    defaultMode: 'search',
    rankingStrategy: 'hybrid',
    preconfiguredSkills: [
      { name: 'playwright', source: 'vercel-labs/agent-skills' },
      { name: 'prisma-expert', source: 'vercel-labs/agent-skills' },
    ],
  },
  read: { maxChars: 16000 },
});

await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  messages,
  tools,
  stopWhen: stepCountIs(6),
});

Configuration reference

findSkillsTool

• mode: "preconfig" | "search"
• query?: text query used in search/ranking
• limit?: 1..25

find config highlights:

• defaultMode, allowedModes
• searchLimit, minConfidence, closeScoreDelta
• rankingStrategy: deterministic | hybrid | ai
• skillsApiBaseUrl, fetchFn
• preconfiguredSkills, aiRanker
• cache (enabled, ttlMs, optional custom store)
• debug (true for console debug or custom logger)
• metrics hooks (onSearchComplete, onError)
• rankingWeights for deterministic scoring weights

readSkillTool

• source?, skillName?, slug?, preferredPath?, maxChars?

read config highlights:

• maxChars, maxCandidatesToRead
• githubToken, fetchFn
• preconfiguredSkills
• cache, debug, metrics
• localSkillsPath for offline/local SKILL.md loading

Examples

See examples/:

• basic.ts
• advanced-ai-ranker.ts
• custom-fetch.ts
• token-auth.ts
• error-handling.ts

Troubleshooting

GitHub API rate limits

• Unauthenticated requests are limited.
• Set githubToken in read config for higher limits.

Invalid source format

• source must be owner/repo (for example vercel-labs/agent-skills).

Search returns no candidates

• Ensure query length is at least 2 characters.
• Lower minConfidence or use preconfig mode with known skills.

FAQ

Does this support offline reads?

Yes. Set read.localSkillsPath to a directory containing <skill>/SKILL.md.

Can I customize ranking?

Yes. Use rankingStrategy: "ai" or "hybrid" with an aiRanker. You can also tune deterministic ranking with rankingWeights.

Can I load metadata only before full content?

Yes. Call readSkillTool with previewOnly: true to get metadata and estimated size.

Is this package ESM/CJS compatible?

Yes. The package exports both ESM and CJS builds from dist/.

Development

pnpm install
pnpm type-check
pnpm build
pnpm test

Docs site

A one-page documentation site is available in docs/index.html.