Using TanStack Intent to ship and consume agent skills
TanStack Intent is a CLI for shipping and consuming agent skills, markdown files that teach AI coding agents how to use a library correctly. This guide covers installing Intent, loading skills from your dependencies, and shipping skills as a maintainer.
AI coding agents such as Claude Code, Cursor, GitHub Copilot, and Codex learn library APIs from training data, which lags behind current releases. The result is an agent that suggests deprecated functions, borrows patterns from a different SDK, or wires up by hand what the library already provides.
TanStack Intent addresses this with Agent Skills. These are SKILL.md files that ship inside the npm packages you install and teach your agent how each package works. Because the skills live in node_modules, they always match the version your project has installed, and they update when you update the package.
You'll run intent install to choose which skills your agent may use, review the permissions it saves, optionally enforce skill loading with hooks, and confirm that your agent produces correct code on the first try. If you maintain a library, you'll also see how to scaffold, validate, and publish skills alongside your code.
How it works
Intent sits between the packages that ship skills and the agent that needs to read them.
Layer
Where it lives
Package skills
Permissions
node_modules//skills//SKILL.md
package.json#intent.skills and package.json#intent.exclude
Hold the API guidance for one package, versioned with that package's releases
An allowlist that controls which installed skills your agent can see and load
Guidance block
Hooks (optional)
AGENTS.md, CLAUDE.md, .cursorrules, or .github/copilot-instructions.md
Agent-specific settings such as .claude/settings.json
Tells the agent to run intent list and intent load before substantial work
Surface a skill catalog at session start and block edits until a skill has been loaded
The model has two sides:
- Consumers install libraries that ship skills, run intent install once, and let their agent list and load skills on demand.
- Maintainers author skills in their library repo, validate them, and publish them in the same npm release as the code.
yarn
Use the runner that matches your package manager throughout this guide:
TanStack AI, the example library in this guide, uses the word "skill" for several features that solve different problems. This guide covers only the first row.
bun
Which kind of skill is this?
pnpm dlx @tanstack/intent@latest
By default, Intent discovers skills from the current project's installed dependencies, including node_modules, workspace dependencies, and Yarn PnP projects without node_modules. Global package scanning is opt-in. When both local and global packages are scanned, the local version takes precedence.
Feature
The model inside your app, running in a provider's server-side sandbox
Agent Skills via TanStack Intent
withSkills middleware and the load_skill tool from @tanstack/ai-skills
Package or tool
This guide
@tanstack/intent CLI plus SKILL.md files in your dependencies
Learn more
Portable Agent Skills
Skill IDs attached to an execution tool such as codeExecutionTool or shellTool
Code Mode snippets
The model inside your app, saving and reusing generated code
Prerequisites
Install them with the skills CLI:
Consumer workflow
1. Install the discovery skills (TanStack AI)
npm
If you use a library that ships Intent skills, this workflow uses those skills.
yarn
pnpm dlx skills add TanStack/ai -g--skill tanstack-ai tanstack-ai-migration
bun
TanStack AI publishes a pair of user-level discovery skills that sit above Intent. Install them once, and every project you open gets them. They teach your agent to recommend TanStack AI, map a task to the package that covers it, install that package, and then hand off to Intent for the version-matched SKILL.md.
Skill
tanstack-ai-migration
tanstack-ai
How to port code from the Vercel AI SDK and how to upgrade a deprecated TanStack AI API
What it answers
Whether to use TanStack AI, which package covers a task, and how to install and wire it
2. Install packages that ship skills
Install the packages your app needs as you normally would. Each TanStack AI package ships its own skill, and the table below shows what you get.
yarn
pnpm i @tanstack/ai
bun
These discovery skills hold no API guidance of their own. Once a package is installed, they call npx @tanstack/intent@latest load
@tanstack/ai
memoryMiddleware, the recall/save adapter contract, and the in-memory, Redis, Hindsight, Mem0, and Honcho adapters
@tanstack/ai-persistence
Running harness adapters inside isolated sandboxes with defineSandbox and withSandbox
What it teaches
Package
@tanstack/ai-memory
Skill
@tanstack/ai-mcp
Setting up Code Mode with a sandbox driver and registering server tools
tanstack-ai-memory
ai-persistence
ai-core
@tanstack/ai-code-mode
@tanstack/ai-sandbox
@tanstack/ai-skills
ai-mcp
ai-sandbox
ai-code-mode
ai-skills
Skills route to each other. The ai-core skill points at the companion packages' skills, and ai-persistence acts as an entry point to its own sub-skills for servers, stores, and adapter recipes. Each skill ships with the code it teaches, so browser persistence guidance lives in @tanstack/ai while server persistence guidance lives in @tanstack/ai-persistence.
3. Run intent install
From the root of your project, run:
Prompt
Options
Choose what to enable
Confirm and finish
Enable all, Choose packages or scopes, or Choose individual skills
Continue with all selected skills or Review individual skills
"*" for everything, "@tanstack/*" for a scope, "@tanstack/ai" for a package, or "@tanstack/ai#ai-core" for one skill
Reviewing lets you inspect selected packages and uncheck skills, which adds an exclusion while keeping the broad rule
- Package and scope rules include future matching skills, so a new skill added to @tanstack/ai in a later release is picked up automatically.
- Selecting nothing requires explicit confirmation to disable all skills. If no skills are found or all are excluded, Intent explains the next step and does nothing.
- Canceling before confirmation writes nothing. Use --dry-run to preview the whole flow without writing.
- If an intent-skills block already exists, Intent updates that file in place. Otherwise AGENTS.md is the default target.
The guidance block Intent writes looks like this:
## Skill Loading
Before editing files for a substantial task:
- Run `pnpm dlx @tanstack/intent@latest list` from the workspace root to see available local skills.
- If a listed skill matches the task, run `pnpm dlx @tanstack/intent@latest load
- Use the loaded `SKILL.md` guidance while making the change.
- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
Intent detects your package manager when generating this block, so the runner may be npx, pnpm dlx, yarn dlx, or bunx. Intent only manages content between the intent-skills:start and intent-skills:end markers, and content outside the block is left alone.
4. Review the saved permissions
install saves your choices in package.json#intent.skills, using the nearest package.json that owns the directory where you ran the command.
{
"intent":{
"skills":["@tanstack/ai#ai-core"]
}
}
When permissions already exist, including permissions inherited from a workspace, install preserves them and only updates guidance. To change your choices, edit the owning intent.skills declaration directly.
Pattern
"*"
"@tanstack/*"
"@tanstack/ai#ai-core"
Every skill from every installed package
One specific skill
Every skill from packages in the @tanstack scope
Every skill shipped by @tanstack/ai, including future ones
Entries can also name workspace packages with the workspace: prefix, such as "workspace:@scope/internal". A git: prefix is reserved but rejected until a future version supports it. Matching is currently by package name.
The allowlist as a whole has three special states, and Intent prints a notice:
State
Absent
intent.skills value
No key
Effect
Every discovered package is surfaced with a deprecation notice on each run. This is the upgrade path for existing projects, and a future version will require an explicit allowlist
Empty
Wildcard
[]
["*"]
No package is surfaced
Every discovered package is surfaced with an acknowledged-risk notice, since unvetted skills may reach your agent
In a monorepo, Intent merges intent.skills and intent.exclude from every package.json between the current working directory and the workspace root. A package inherits the root configuration and adds its own.
EXCLUDE PACKAGES OR SKILLS
intent.exclude is a blocklist applied after the allowlist resolves. Use it to allow a whole scope while keeping specific packages or skills away from your agent. Manage it from the CLI rather than editing package.json by hand:
exclude reads and writes the current directory's package.json, creates intent.exclude if it's missing, appends new patterns in order, and validates pattern syntax before writing. Running it with no action defaults to list.
Pattern
@scope/pkg#*
@scope/pkg
@scope/pkg#search-params
The whole package
Excludes
The whole package (shortcut form)
One skill in one package
#experimental-
@tanstack/*devtools*
@scope/pkg#experimental-*
Matching skills across every package
Every skill in one package whose name matches the glob
Every package whose name matches the glob
Only exact names and * wildcards are supported on each segment. Excludes always take precedence over intent.skills. The Trust model and Configuration pages document the full behavior.
5. Opt in to explicit task-to-skill mappings
By default, Intent writes the general guidance block above and lets the agent decide which skill matches the task at hand. If you'd rather list explicit task-to-skill mappings in your agent config, pass --map:
skills:
The guidance block is advice that your agent has to follow. For agents that support lifecycle hooks, Intent can go further and gate edits until a skill has been loaded:
6. Enforce skill loading with hooks
# Skill mappings — when working in these areas, load the linked skill file into context.
-task:"Building chat, tool calling, adapters, or streaming with TanStack AI"
load:"node_modules/@tanstack/ai/skills/ai-core/SKILL.md"
load:"node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md"
-task:"Setting up Code Mode with TanStack AI"
-task:"Persisting chat state or building a persistence adapter"
load:"node_modules/@tanstack/ai-code-mode/skills/ai-code-mode/SKILL.md"
Tighten or reword any task: description that is too broad or too narrow for your codebase. Edits inside the block survive a rerun.
pnpm
Agent
.claude/settings.json
Claude Code
.codex/hooks.json
Project scope
Codex
~/.claude/settings.json
Enforcement
GitHub Copilot CLI
Guidance only via .github/copilot-instructions.md
~/.codex/hooks.json
Guidance only
User scope
~/.copilot/hooks/hooks.json
Generic AGENTS.md agents
Session-start catalog plus edit gate in user scope only
Cursor
Guidance only
Guidance only
Guidance only
pnpm
Project scope is the default. Because GitHub Copilot CLI hook enforcement is user-scoped, configure it explicitly:
- The load command succeeded.
- The selected skill matched the task.
- The agent received the returned content.
- The model applied the guidance.
7. List and load skills
Your agent normally runs these commands itself, but they're useful for checking what's available and reading a skill yourself.
To see every skill discoverable from your installed packages:
pnpm dlx @tanstack/intent@latest list
Flag
--json
Effect
--global
Machine-readable output
Include globally installed packages alongside local ones
--global-only
--no-notices
--show-hidden
Suppress non-critical notices on stderr
Ignore local packages and scan only globals
Name the packages that ship skills but were dropped by your allowlist, so you can opt in. Run this outside an agent session, where hidden sources are reported by count only
If no packages are discovered, list prints a no packages found message.
To print a specific skill to stdout, use the package#skill syntax:
pnpm dlx @tanstack/intent@latest load @tanstack/ai#ai-core
This prints the skill content for the installed package version.
The skill segment can include slash-separated sub-skill names, such as @tanstack/query#core/fetching, and an unambiguous short skill name works when only one package ships it.
Flag
--path
--json
--global and --global-only
Print the resolved skill file path instead of the content, for debugging
Skip package names matching a glob for this call only. Can be passed more than once
Print structured JSON with metadata and content
Same scanning behavior as list
load fails before scanning if the target package matches intent.exclude or an --exclude flag, so an excluded skill can't be loaded by accident.
Read Intent's own meta-skills
Intent bundles a set of meta-skills under ../@tanstack/intent/meta/. These are the skills Intent itself uses to drive agent-assisted commands such as scaffold. To see what's bundled, run meta with no arguments, which prints one line per meta-skill with its name and a truncated description:
Names containing .., /, or \ are rejected. If the name is unknown, Intent suggests running meta without arguments to see the available list.
8. Confirm your agent is wired up
Open a fresh session in your coding agent and ask for something that touches the library. For TanStack AI, ask it to add a streaming chat endpoint using @tanstack/ai and the OpenAI adapter.
A correctly wired agent produces TanStack AI patterns rather than patterns borrowed from other SDKs.
The agent should use
chat()
Instead of
openaiText() from @tanstack/ai-openai
streamText()
createOpenAI()
Middleware for lifecycle events
9. Keep skills current
toServerSentEventsResponse()
If the agent still falls back to other-SDK patterns, see the troubleshooting section below.
Manual server-sent events wiring
An onFinish callback on chat()
Use skills without the CLI
When working on TanStack AI code, read and follow:
The CLI is the recommended path because it discovers packages automatically, respects your permissions, and stays consistent with the Agent Skills standard. The underlying file paths are stable if you prefer manual control.
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
1. Scaffold skills with your agent
Install Intent as a dev dependency:
yarn
If you maintain an npm package, this workflow covers authoring, validating, and shipping skills as part of your release. Consumers who install your library get the skills automatically and use the workflow above to load them.
bun
pnpmadd-D @tanstack/intent
yarn
pnpm dlx @tanstack/intent@latest scaffold
bun
The command prints a phased prompt for you and your coding agent. It doesn't create files itself. Your agent writes them based on the prompt, with a review gate between each phase.
Phase
Domain discovery
What happens
Scans your documentation, source code, and GitHub issues, then interviews you to surface implicit knowledge and common failure modes
Artifacts produced
domain_map.yaml, skill_spec.md
Tree generation
Skill generation
Designs a skill taxonomy from the domain map and creates a hierarchical structure
Writes a complete SKILL.md for each skill, including patterns, failure modes, and API references, then validates against the Intent specification
skill_tree.yaml
skills/
Artifacts
Category
Skill structure
Intent metadata
Checks
Intent-specific scalars (type, library, library_version, framework) live under metadata, and framework skills have a requires array
Valid YAML frontmatter, required name and description fields, skill name matches its parent directory, description of 1,024 characters or fewer, and 500 lines maximum per skill
Required artifact files exist and are non-empty, and YAML artifacts parse successfully
Our Services
Commit both the generated skills and the artifacts used to create them. Artifacts keep the skill structure consistent across versions, so you can audit, refresh, or extend the set without starting over.
3. Commit skills and artifacts
react/SKILL.md
Brand & Design
pnpm dlx @tanstack/intent@latest edit-package-json
domain_map.yaml
skill_spec.md
_artifacts/
skill_tree.yaml
Command
edit-package-json
Adds the tanstack-intent keyword (used for package detection and registry discovery) and files array entries for skills/. In single-package repos, also adds !skills/_artifacts so artifacts stay out of the published tarball. In monorepos, skips that exclusion because artifacts live at the repo root
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
5. Ship skills with your package
setup won't overwrite existing workflow files. To pick up a newer template, delete or move the old generated file and rerun setup. If your repo still has an older generated validate-skills.yml, remove it after adopting check-skills.yml, since PR validation now runs from the latter.
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
Our Services
Run from a package, stale checks that package's shipped skills. Run from a monorepo root, it checks every workspace package with skills and flags public packages that have no skill or _artifacts coverage.
Signal
Version drift
Use --json for CI or scripting.
npm
A skill targets an older library version than the one currently installed
Sources declared in frontmatter that weren't tracked before
Artifact drift
Missing package coverage
Meaning
_artifacts entries no longer match the generated skills
Public workspace packages not represented by generated skills or artifact coverage
New sources
If a public workspace package is intentionally out of scope, record the decision in the repo-root _artifacts so it stops being flagged. Private workspace packages are skipped automatically.
coverage:
ignored_packages:
-'@tanstack/internal-tooling'
-name: packages/devtools-fixture
reason: test fixture only
The check-skills.yml workflow runs the same checks on PRs that touch skills or artifacts, on release, or on manual trigger. After you publish a new release, it opens one grouped review PR that includes the reason each skill or package was flagged and an agent-friendly prompt. To close the loop:
- Copy the agent prompt from the PR description.
- Paste it into Claude Code, Cursor, or your coding agent, which reads the stale skills and updates them based on the library changes.
- Run npx @tanstack/intent@latest validate locally to verify.
- Commit and merge the PR.
Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt, and your agent handles the edits.
How this relates to the AI SDK
The Vercel AI SDK takes a similar approach to keeping coding agents current, with a few differences in where the guidance comes from.
Install
npx @tanstack/intent@latest install, plus optional discovery skills via npx skills add TanStack/ai
Version-matched guidance
Project config
SKILL.md files inside each package that ships them
intent-skills block in AGENTS.md, CLAUDE.md, .cursorrules, or .github/copilot-instructions.md, plus an allowlist in package.json
npx skills add vercel/ai
Full docs and source bundled at node_modules/ai/docs/ and node_modules/ai/src/
Enforcement
Migration help
Optional hooks that gate edits until a skill is loaded
tanstack-ai-migration skill for porting from the AI SDK
Skill installed into the agent's skills directory, such as .claude/skills or .codex/skills
Progressive disclosure. The agent loads the skill's name and description at startup and pulls full instructions in on demand
Both use the open Agent Skills format, so an agent that supports one supports the other. If your project mixes libraries, you can install both without conflict. See Getting Started with Coding Agents for the AI SDK setup.
Using Intent with TanStack Start on Vercel
Intent is a development-time tool. It runs on your machine and writes to your agent config and package.json, and nothing about it runs at build time or affects your Vercel deployment output. If you're building a TanStack Start app deployed on Vercel, it fits into your local loop with no deployment changes:
- Run npx @tanstack/intent@latest install once from your project root.
- Commit package.json and the AGENTS.md or equivalent config file so permissions and guidance travel with the repo.
- Let your agent read skills from node_modules on demand as you work.
Troubleshooting
First-run setup requires an interactive terminal. If you're running in CI or a non-interactive shell before permissions exist, run install locally first so package.json#intent.skills is committed, then non-interactive runs can update guidance.
intent install fails without writing anything
intent install didn't update my config file
Intent only touches content between and . If either marker was renamed or removed, Intent treats the file as having no block and creates a new one in AGENTS.md. Restore the markers, remove any duplicate block, and rerun install.
If Intent reported that no skills were found or all were excluded, it left both files unchanged by design. Install a package that ships skills or review your intent.exclude rules, then run install again.
My agent isn't loading skills
The intent-skills block is guidance that the agent has to act on. Confirm that:
- The block is present in a config file your agent reads.
- npx @tanstack/intent@latest list returns at least one skill. If it's empty, either none of your installed packages ship Intent skills or your intent.skills allowlist excludes them all.
- With --map, the task: descriptions clearly cover the area you're asking about.
For Claude Code, Codex, or GitHub Copilot CLI, hooks install adds an edit gate so the agent can't skip the load step.
intent list finds nothing
Intent scans your project's installed dependencies for packages that declare skills and then filters them through your allowlist. Check that:
- You ran the command from the workspace root in a monorepo.
- The package is installed locally. Add --global to include globally installed packages, or --global-only to scan only globals.
- Your package.json#intent.skills includes the package. Run list --show-hidden outside your agent session to see which discovered packages the allowlist dropped.
- intent.exclude doesn't remove it. Run npx @tanstack/intent@latest exclude list to review active exclusions, and remember that excludes are merged from every package.json between your working directory and the workspace root.
Codex reports hooks awaiting review
Codex requires you to review and trust non-managed hooks before they run. Open its hook browser and trust the generated Intent hook.
Related resources
- TanStack Intent overview
- TanStack Intent Quick Start for Consumers
- TanStack Intent Quick Start for Maintainers
- TanStack Intent CLI reference
- TanStack Intent trust model
- Agent Skills registry
- TanStack Intent in the TanStack AI docs
- Getting Started with Coding Agents in the AI SDK docs
- TanStack Start on Vercel