--- 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 ```typescript 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.', }) export async function POST(request: Request) { const { messages } = await request.json() const stream = chat({ adapter: anthropicText('claude-sonnet-4-6'), messages, middleware: [withSkills(pptx)], }) return toServerSentEventsResponse(stream) } ``` `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. ```ts import { toolDefinition } from '@tanstack/ai' import { z } from 'zod' // Your own runner: a provider sandbox, a Code Mode isolate, a remote worker. import { runSomewhere } from './shell' 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) })) // chat({ tools: [executeShell], middleware: [withSkills(source)] }) ``` 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: ```typescript import { runSkillSourceConformance } from '@tanstack/ai-skills/testing' // Your SkillSource implementation, seeded with the `alpha` / `beta` fixture // skills the suite expects. import { myS3Source } from './my-s3-source' import { fixtures } from './fixtures' 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`