Using TanStack Intent to ship and consume agent skills

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.

Copy link to headingHow it works

Intent sits between the packages that ship skills and the agent that needs to read them.

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.

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.

Use the runner that matches your package manager throughout this guide:

pnpm dlx @tanstack/intent@latest <command>

npx @tanstack/intent@latest <command>

yarn dlx @tanstack/intent@latest <command>

bunx @tanstack/intent@latest <command>

Copy link to headingWhich kind of skill is this?

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.

Copy link to headingPrerequisites

• Node.js 22+ and a package manager (npm, pnpm, Yarn, or Bun).
• An AI coding agent that reads a project-level config file such as AGENTS.md, CLAUDE.md, .cursorrules, or .github/copilot-instructions.md.
• For the consumer workflow, at least one installed dependency that ships Intent skills. list and load return nothing useful without one. Browse the TanStack Intent skills registry to see which packages qualify.

Copy link to headingConsumer workflow

If you use a library that ships Intent skills, this workflow uses those skills.

Copy link to heading1. Install the discovery skills (TanStack AI)

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.

Install them with the skills CLI:

pnpm dlx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration

npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration

yarn dlx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration

bunx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration

These discovery skills hold no API guidance of their own. Once a package is installed, they call npx @tanstack/intent@latest load <package>#<skill> so the agent reads the skill that matches the installed version. This step is specific to TanStack AI. Other libraries that ship Intent skills may not have an equivalent, and Intent works without it.

Copy link to heading2. 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.

pnpm i @tanstack/ai

npm i @tanstack/ai

yarn add @tanstack/ai

bun add @tanstack/ai

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.

Copy link to heading3. Run intent install

From the root of your project, run:

pnpm dlx @tanstack/intent@latest install

npx @tanstack/intent@latest install

yarn dlx @tanstack/intent@latest install

bunx @tanstack/intent@latest install

On first use, Intent walks you through choosing which installed packages and skills your agent may use, then writes permissions and a guidance block.

A few behaviors to know before you run it:

• 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:

<!-- intent-skills:start -->
## 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 <package>#<skill>` before changing files.
- 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-skills:end -->

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.

Copy link to heading4. 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.

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:

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.

Copy link to headingExclude 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:

pnpm dlx @tanstack/intent@latest exclude add @tanstack/router#experimental-*
pnpm dlx @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
pnpm dlx @tanstack/intent@latest exclude list --json

npx @tanstack/intent@latest exclude add @tanstack/router#experimental-*
npx @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
npx @tanstack/intent@latest exclude list --json

yarn dlx @tanstack/intent@latest exclude add @tanstack/router#experimental-*
yarn dlx @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
yarn dlx @tanstack/intent@latest exclude list --json

bunx @tanstack/intent@latest exclude add @tanstack/router#experimental-*
bunx @tanstack/intent@latest exclude remove @tanstack/router#experimental-*
bunx @tanstack/intent@latest exclude list --json

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.

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.

Copy link to heading5. 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:

pnpm dlx @tanstack/intent@latest install --map

npx @tanstack/intent@latest install --map

yarn dlx @tanstack/intent@latest install --map

bunx @tanstack/intent@latest install --map

With --map, the block maps task descriptions to skill files. Your agent reads the task: descriptions to decide when to pull a skill into context, so they should match the areas you work in.

<!-- 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 -->

Tighten or reword any task: description that is too broad or too narrow for your codebase. Edits inside the block survive a rerun.

Copy link to heading6. Enforce skill loading with hooks

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:

pnpm dlx @tanstack/intent@latest hooks install

npx @tanstack/intent@latest hooks install

yarn dlx @tanstack/intent@latest hooks install

bunx @tanstack/intent@latest hooks install

Hooks return the available skill catalog as context when a session starts, then block supported edit tools until the hook observes a recognized intent load <skill-id> command. The catalog respects intent.skills and intent.exclude in package.json.

Project scope is the default. Because GitHub Copilot CLI hook enforcement is user-scoped, configure it explicitly:

pnpm dlx @tanstack/intent@latest hooks install --scope user --agents copilot

npx @tanstack/intent@latest hooks install --scope user --agents copilot

yarn dlx @tanstack/intent@latest hooks install --scope user --agents copilot

bunx @tanstack/intent@latest hooks install --scope user --agents copilot

hooks install does not write the guidance block, so run intent install separately if you want both. Hooks are an edit gate and an observation signal, not proof of correct behavior. They do not verify that:

• The load command succeeded.
• The selected skill matched the task.
• The agent received the returned content.
• The model applied the guidance.

Copy link to heading7. 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

npx @tanstack/intent@latest list

yarn dlx @tanstack/intent@latest list

bunx @tanstack/intent@latest list

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

npx @tanstack/intent@latest load @tanstack/ai#ai-core

yarn dlx @tanstack/intent@latest load @tanstack/ai#ai-core

bunx @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.

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.

Copy link to headingRead 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:

pnpm dlx @tanstack/intent@latest meta

npx @tanstack/intent@latest meta

yarn dlx @tanstack/intent@latest meta

bunx @tanstack/intent@latest meta

To print one meta-skill's SKILL.md, pass its directory name:

pnpm dlx @tanstack/intent@latest meta <name>

npx @tanstack/intent@latest meta <name>

yarn dlx @tanstack/intent@latest meta <name>

bunx @tanstack/intent@latest meta <name>

Names containing .., /, or \ are rejected. If the name is unknown, Intent suggests running meta without arguments to see the available list.

Copy link to heading8. 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.

If the agent still falls back to other-SDK patterns, see the troubleshooting section below.

Copy link to heading9. Keep skills current

Skills are versioned with the package that ships them, so when you update a library, the skills update too:

pnpm update @tanstack/ai

npm update @tanstack/ai

yarn up @tanstack/ai

bun update @tanstack/ai

No CLI rerun is needed after an update. Rerun npx @tanstack/intent@latest install only when:

• You add a new Intent-enabled package, such as adding @tanstack/ai-code-mode to an existing project, and your permissions don't already cover it with a package or scope rule.
• You want to refresh the guidance block or task mappings in your agent config.

To check whether any installed skills reference outdated source documentation:

pnpm dlx @tanstack/intent@latest stale

npx @tanstack/intent@latest stale

yarn dlx @tanstack/intent@latest stale

bunx @tanstack/intent@latest stale

Update notifications for changed skill instructions are not available yet.

Copy link to headingUse skills without the CLI

If you'd rather manage your agent config by hand, reference the skill files directly from node_modules. 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 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.

Copy link to headingMaintainer workflow

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.

Install Intent as a dev dependency:

pnpm add -D @tanstack/intent

npm i -D @tanstack/intent

yarn add -D @tanstack/intent

bun add -d @tanstack/intent

Copy link to heading1. Scaffold skills with your agent

pnpm dlx @tanstack/intent@latest scaffold

npx @tanstack/intent@latest scaffold

yarn dlx @tanstack/intent@latest scaffold

bunx @tanstack/intent@latest scaffold

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.

Plan for multiple review rounds and regular context compaction. The more concrete patterns, pitfalls, and real-world usage problems you supply during the interview, the better the generated skills.

Copy link to heading2. Validate before publishing

pnpm dlx @tanstack/intent@latest validate

npx @tanstack/intent@latest validate

yarn dlx @tanstack/intent@latest validate

bunx @tanstack/intent@latest validate

Validation enforces the SKILL.md format and packaging rules. Wire it into CI so a malformed skill blocks a release the same way a failing test would.

Copy link to heading3. Commit skills and artifacts

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.

skills/
  core/SKILL.md
  react/SKILL.md
  _artifacts/
    domain_map.yaml
    skill_spec.md
    skill_tree.yaml

Copy link to heading4. Configure your package for publishing

Two helper commands prepare your package to ship skills:

pnpm dlx @tanstack/intent@latest edit-package-json
pnpm dlx @tanstack/intent@latest setup

npx @tanstack/intent@latest edit-package-json
npx @tanstack/intent@latest setup

yarn dlx @tanstack/intent@latest edit-package-json
yarn dlx @tanstack/intent@latest setup

bunx @tanstack/intent@latest edit-package-json
bunx @tanstack/intent@latest setup

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.

Copy link to heading5. Ship skills with your package

Skills publish inside your npm package with no extra step:

npm publish

Packaging code and skills together keeps their versions aligned. intent load on the consumer side returns skill content from whichever package version is installed.

Copy link to heading6. Track staleness against source docs

pnpm dlx @tanstack/intent@latest stale

npx @tanstack/intent@latest stale

yarn dlx @tanstack/intent@latest stale

bunx @tanstack/intent@latest stale

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.

Use --json for CI or scripting.

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:

1. Copy the agent prompt from the PR description.
2. Paste it into Claude Code, Cursor, or your coding agent, which reads the stale skills and updates them based on the library changes.
3. Run npx @tanstack/intent@latest validate locally to verify.
4. 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.

Copy link to headingHow 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.

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.

Copy link to headingUsing 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.

Copy link to headingTroubleshooting

Copy link to headingintent install fails without writing anything

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.

Copy link to headingintent install didn't update my config file

Intent only touches content between <!-- intent-skills:start --> and <!-- intent-skills:end -->. 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.

Copy link to headingMy 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.

Copy link to headingintent 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.

Copy link to headingCodex 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.

Copy link to headingFurther building

Use vercelGatewayDecider from TanStack AI’s Vercel AI Gateway adapter with Jev in Moderate product reviews with Jev, TanStack AI, and AI Gateway to get typed choices, scores, and boolean probabilities instead of generated text.

Copy link to headingRelated 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
• Using Jev in TanStack Start with TanStack AI