Agent Skills (TanStack Intent)

Looking for runtime skills inside Code Mode? Those are a different feature — see Code Mode with Skills. This page is about agent-authoring skills: markdown files that teach your coding assistant how TanStack AI works.

Step 1: Install TanStack AI#

If you haven't already, install @tanstack/ai plus any adapter packages you need. See the Quick Start for a full walkthrough.

pnpm add @tanstack/ai

Step 2: Run intent install#

From the root of your project, run:

npx @tanstack/intent@latest install

What are Agent Skills?#

Agent Skills are markdown documents (SKILL.md) that ship inside npm packages and tell AI coding agents how to use a library correctly — which functions to use, which patterns to avoid, and when to reach for which module. The format is an open standard supported by Claude Code, Cursor, GitHub Copilot, Codex, and others.

TanStack AI publishes skills inside its packages so the guidance travels with npm update instead of being pinned in a model's training data or copy-pasted into CLAUDE.md manually.

Skills Shipped by TanStack AI#

Skills route to each other: ai-core points at the companion packages' skills, and ai-persistence is an entry point that routes to its own sub-skills (server, stores, and the build-{drizzle,prisma,cloudflare,custom}-adapter recipes) under skills/ai-persistence/, same nesting style as ai-core. Multi-instance locks ship with the code they teach, so ai-core/locks lives in @tanstack/ai alongside withLocks.

Each skill ships with the code it teaches. Browser persistence lives in the framework packages, so ai-core/client-persistence is in @tanstack/ai rather than in @tanstack/ai-persistence — an app that persists only in the browser never installs the server package.

Each skill lives under node_modules/<package>/skills/<skill-name>/SKILL.md once the package is installed.

Step 3: Review the Generated Mappings#

The install command appends (or creates) an intent-skills block that looks like this:

<!-- intent-skills:start -->
# Skill mappings — when working in these areas, load the linked skill file into context.
skills:
  - task: "Building chat, tool calling, adapters, or streaming with TanStack AI"
    load: "node_modules/@tanstack/ai/skills/ai-core/SKILL.md"
  - task: "Persisting chat state or building a persistence adapter"
    load: "node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md"
  - task: "Setting up Code Mode with TanStack AI"
    load: "node_modules/@tanstack/ai-code-mode/skills/ai-code-mode/SKILL.md"
<!-- intent-skills:end -->

Check that the task: descriptions match areas you actually work in. Tighten or reword them if needed — they're how your agent decides when to pull the skill into context.

Step 4: Confirm It's Wired Up#

Open a fresh session in your coding agent and ask it to build something with TanStack AI — for example: "Add a streaming chat endpoint using @tanstack/ai and the OpenAI adapter."

You should see:

• The agent uses chat(), not streamText().
• The adapter is imported as openaiText() from @tanstack/ai-openai, not createOpenAI().
• The response is wrapped with toServerSentEventsResponse() instead of manual SSE wiring.
• Middleware is used for lifecycle events (no onFinish callback on chat()).

If the agent still falls back to other-SDK patterns, re-open its config file and confirm the intent-skills block is present and the task: descriptions clearly cover the area you're asking about.

Keeping Skills Current#

Skills are versioned with the package. When you bump @tanstack/ai, the SKILL.md files under node_modules update with it — no CLI re-run needed. Re-run npx @tanstack/intent@latest install only when you add a new intent-enabled package (for example, adding @tanstack/ai-code-mode later) or want to refresh the task mappings.

Using Skills Without the CLI#

If you'd rather wire skills in yourself, you can reference them directly from node_modules in any agent config file. The minimum your agent needs is a pointer to the file:

When working on TanStack AI code, read and follow:
node_modules/@tanstack/ai/skills/ai-core/SKILL.md

The CLI is recommended because it discovers packages automatically and stays consistent with the agent-skills standard, but the underlying file paths are stable.

Learn More#

• TanStack Intent documentation — the CLI's full reference, including scaffold, validate, and CI setup for library maintainers.
• Agent Skills registry — browse other intent-enabled packages.