@tanstack/ai-skills weekly downloads statistics

@tanstack/ai-skills

Portable Agent Skills (SKILL.md) as a first-class chat() middleware for TanStack AI

withSkills renders a short catalog of the skills you offer into the system prompt and gives the model a load_skill tool. The model reads the catalog, picks a skill, and pulls the full instructions only when it needs them — so a large skill library does not tax every request. This is the portable path: it runs on any tool-calling model, with no provider sandbox. For skills that run in a provider's own sandbox, see Provider Skills; the two do not mix in one call.

Installation

Usage

Define a skill and pass it to withSkills in the middleware array. The middleware handles the catalog and the load_skill tool for you.

Pass an array to offer several; they are sorted by name and deduped. Loading the same skill twice in one conversation returns a short "already loaded" marker instead of repeating the body.

Tuning the catalog

The catalog is rendered per model family — Anthropic models get the XML they are tuned for, everything else a plain markdown list — and you can override that with renderCatalog or an instructionTemplate.

Where skills come from

Inline skills are the quickest start, but skills usually live somewhere else. Each source is on its own entry point:

| Source | Import | Use when |

| inlineSkill(...) | @tanstack/ai-skills | Defining a skill in code | | skillDirectory(...) | @tanstack/ai-skills/node | Walking a folder of SKILL.md files — reads the filesystem, so server only | | staticSkills(catalog) | @tanstack/ai-skills/static | A build-time bundle, no filesystem at runtime (edge-safe). Pair with skillsCatalogPlugin from /node in your Vite config | | Your own SkillSource | — | Skills in S3, a database, a registry |

aggregate, dedupe, filter, cache, and combineSources compose these.

Writing your own source

Implement the SkillSource contract, then prove it with the conformance suite the package ships:

It checks the things that break in production: a missing skill throws rather than returning empty, resources load while a path like ../../etc/passwd is rejected, revision() is stable across identical content, and concurrent list() calls stay consistent. The optional parts of the contract are only checked when you implement them — the resource cases need both listResources and readResource, and the revision case needs revision — so a source that cannot represent them is skipped rather than failed. vitest is an optional peer dependency for this entry point.

Documentation

• Portable Agent Skills: what the model sees, catalog options, reading a skill's bundled files • Skill sources: folder, build-time bundle, your own store, and combining them • Writing a skill source: the SkillSource contract and the conformance suite

License

MIT