| name | ai-skills |
| description | Portable Agent Skills (SKILL.md) for TanStack AI with @tanstack/ai-skills. Renders a skill catalog and a load_skill tool via the withSkills middleware so any tool-calling model loads skills on demand, on any provider. Covers the SkillSource interface, inlineSkill/skillDirectory/staticSkills, the aggregate/ dedupe/filter/cache combinators, read_skill_resource, and the conformance suite. Use for provider-agnostic runtime skills — NOT hosted provider skills (codeExecutionTool/shellTool), which run in a provider sandbox.
|
| type | core |
| library | tanstack-ai |
| library_version | 0.0.0 |
| sources | ["TanStack/ai:docs/skills/agent-skills.md","TanStack/ai:docs/skills/skill-sources.md","TanStack/ai:docs/skills/writing-adapters.md","TanStack/ai:docs/tools/provider-skills.md"] |
TanStack AI Skills
Builds on the ai-core skill in @tanstack/ai. Package: @tanstack/ai-skills.
Portable Agent Skills give a tool-calling model a library of SKILL.md skills it
can load on demand, on any provider, with no server sandbox. This is separate
from hosted Provider Skills (codeExecutionTool / shellTool), which run in
the provider's sandbox and are referenced by ID.
Two skill features, do not confuse them
| Need | Use |
|---|
| Model loads SKILL.md at runtime, any provider | withSkills (this package) |
| Hosted skill runs in a provider sandbox by ID | codeExecutionTool / shellTool |
| Teach a coding assistant how to use TanStack AI | Ship a SKILL.md, install via Intent |
The portable and hosted paths do not mix in one chat() call: withSkills
throws if a code_execution/shell tool in the same call carries skills.
Add skills to a chat
import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { anthropicText } from '@tanstack/ai-anthropic'
import { inlineSkill, withSkills } from '@tanstack/ai-skills'
const pptx = inlineSkill({
name: 'pptx-builder',
description: 'Build and edit PowerPoint decks with python-pptx.',
instructions: '# Building a deck\nUse python-pptx. Edit slides, then save.',
})
const stream = chat({
adapter: anthropicText('claude-sonnet-4-5'),
messages,
middleware: [withSkills(pptx)],
})
withSkills adds a catalog to the system prompt and a load_skill tool whose
name is constrained to your skill names. It renders <available_skills> XML
for Anthropic models and markdown for the rest. Re-loading a skill in the same
conversation returns a short "already loaded" marker.
Sources
A SkillSource is bytes only (no filesystem assumption), so the middleware runs
on the edge too.
inlineSkill({ name, description, instructions, resources? }) — one skill in
code or a DB row. Edge-safe.skillDirectory(root, { strict? }) — walk a folder for SKILL.md. Import from
@tanstack/ai-skills/node (uses node:fs). Strict by default.staticSkills(catalog) — build-time bundle via skillsCatalogPlugin (Vite).
Edge-safe, and .names is a typed union.
Combine with aggregate, dedupe, filter, cache. withSkills([a, b]) is
sugar for dedupe(aggregate([a, b])). A single source is never auto-wrapped, so
a tenant-scoped source is never cached into a shared bucket.
Resources
To let the model read a skill's bundled files, pass createResourceTool(source)
in tools. withSkills detects it and advertises read_skill_resource. Paths
that escape the skill root are rejected.
Skills that carry code
withSkills inventories a skill's scripts/ in the load_skill result but does
NOT run them (script execution is a later phase). To let a skill run code, pass
your own execution tool to chat({ tools }) alongside withSkills and write the
skill so it tells the model to call that tool. withSkills composes with any
tools you provide.
import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'
const executeShell = toolDefinition({
name: 'execute_shell',
description: 'Run a shell command and return its stdout.',
inputSchema: z.object({ command: z.string() }),
outputSchema: z.object({ stdout: z.string() }),
}).server(async ({ command }) => ({ stdout: await runSomewhere(command) }))
The skill supplies the command; your tool supplies the ability to run it. Swap in
a provider sandbox, a Code Mode isolate, or a remote worker without changing the
skill. For hosted skills that run in the provider's own sandbox, use
codeExecutionTool / shellTool instead (see provider-skills).
Write a custom source
Implement SkillSource (list + load, optional revision/listResources/
readResource), then validate it with the shipped conformance suite:
import { runSkillSourceConformance } from '@tanstack/ai-skills/testing'
runSkillSourceConformance(() => myS3Source(fixtures), 's3')
Entry points
@tanstack/ai-skills — types, inlineSkill, combinators, withSkills,
createResourceTool, validateSkill, staticSkills, SkillLimitError.@tanstack/ai-skills/node — skillDirectory, skillsCatalogPlugin (node:fs).@tanstack/ai-skills/testing — runSkillSourceConformance.
Docs
- Portable Agent Skills:
docs/skills/agent-skills.md
- Skill sources:
docs/skills/skill-sources.md
- Write a skill source:
docs/skills/writing-adapters.md
- Provider (hosted) skills:
docs/tools/provider-skills.md
