---
title: Using TanStack Intent to ship and consume agent skills
description: 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.
url: "https://vercel.com/kb/guide/tanstack-intent"
published: 2026-09-17
last_updated: 2026-09-17
authors: Ben Sabic
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

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.

> TanStack Intent is in **alpha** at the time of writing. Commands and output formats may change before a stable release.

## How it works

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

| Layer            | Where it lives                                                                 | What it does                                                                           |
| ---------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Package skills   | `node_modules/<package>/skills/<skill-name>/SKILL.md`                          | Hold the API guidance for one package, versioned with that package's releases          |
| Permissions      | `package.json#intent.skills` and `package.json#intent.exclude`                 | An allowlist that controls which installed skills your agent can see and load          |
| Guidance block   | `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md` | Tells the agent to run `intent list` and `intent load` before substantial work         |
| Hooks (optional) | Agent-specific settings such as `.claude/settings.json`                        | 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.
  

By default, Intent discovers skills from the current project's installed dependencies, including `node_modules`, workspace dependencies, and [Yarn PnP projects](https://yarnpkg.com/features/pnp) 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**

```bash
pnpm dlx @tanstack/intent@latest <command>
```

**npm**

```bash
npx @tanstack/intent@latest <command>
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest <command>
```

**bun**

```bash
bunx @tanstack/intent@latest <command>
```

## Which 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.

| Feature                          | Audience                                                               | Package or tool                                                                    | Learn more                                                                                       |
| -------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Agent Skills via TanStack Intent | Your coding assistant, at development time                             | `@tanstack/intent` CLI plus `SKILL.md` files in your dependencies                  | This guide                                                                                       |
| Portable Agent Skills            | The model inside your app, at runtime                                  | `withSkills` middleware and the `load_skill` tool from `@tanstack/ai-skills`       | [Portable Agent Skills](https://tanstack.com/ai/latest/docs/skills/agent-skills)                 |
| Provider Skills                  | The model inside your app, running in a provider's server-side sandbox | Skill IDs attached to an execution tool such as `codeExecutionTool` or `shellTool` | [Provider Skills](https://tanstack.com/ai/latest/docs/tools/provider-skills)                     |
| Code Mode snippets               | The model inside your app, saving and reusing generated code           | `@tanstack/ai-code-mode`                                                           | [Code Mode with Snippets](https://tanstack.com/ai/latest/docs/code-mode/code-mode-with-snippets) |

## Prerequisites

- Node.js 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](https://tanstack.com/intent/registry) to see which packages qualify.
  

## Consumer workflow

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

### 1\. 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](https://www.skills.sh/) CLI:

**pnpm**

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

**npm**

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

**yarn**

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

**bun**

```bash
bunx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration
```
| Skill                   | What it answers                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `tanstack-ai`           | Whether to use TanStack AI, which package covers a task, and how to install and wire it |
| `tanstack-ai-migration` | How to port code from the Vercel AI SDK and how to upgrade a deprecated TanStack AI API |

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.

### 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.

**pnpm**

```bash
pnpm i @tanstack/ai
```

**npm**

```bash
npm i @tanstack/ai
```

**yarn**

```bash
yarn add @tanstack/ai
```

**bun**

```bash
bun add @tanstack/ai
```
| Package                    | Skill                | What it teaches                                                                                                                                                         |
| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@tanstack/ai`             | `ai-core`            | Chat experience, browser persistence on `useChat`, tool calling, adapters, middleware, locks, structured outputs, media generation, AG-UI protocol, and custom backends |
| `@tanstack/ai-persistence` | `ai-persistence`     | Server chat state with `withPersistence`, the store contracts, and per-stack recipes for Drizzle, Prisma, or Cloudflare D1                                              |
| `@tanstack/ai-memory`      | `tanstack-ai-memory` | `memoryMiddleware`, the recall/save adapter contract, and the in-memory, Redis, Hindsight, Mem0, and Honcho adapters                                                    |
| `@tanstack/ai-mcp`         | `ai-mcp`             | Connecting to MCP servers, running their tools inside `chat()`, resources, prompts, and the type-generating CLI                                                         |
| `@tanstack/ai-sandbox`     | `ai-sandbox`         | Running harness adapters inside isolated sandboxes with `defineSandbox` and `withSandbox`                                                                               |
| `@tanstack/ai-code-mode`   | `ai-code-mode`       | Setting up Code Mode with a sandbox driver and registering server tools                                                                                                 |
| `@tanstack/ai-skills`      | `ai-skills`          | Portable Agent Skills at runtime, including `withSkills`, `load_skill`, the `SkillSource` interface, and `inlineSkill`, `skillDirectory`, and `staticSkills`            |

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:

**pnpm**

```bash
pnpm dlx @tanstack/intent@latest install
```

**npm**

```bash
npx @tanstack/intent@latest install
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest install
```

**bun**

```bash
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.

| Prompt                | Options                                                                        | What gets saved                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Choose what to enable | **Enable all**, **Choose packages or scopes**, or **Choose individual skills** | `"*"` for everything, `"@tanstack/*"` for a scope, `"@tanstack/ai"` for a package, or `"@tanstack/ai#ai-core"` for one skill |
| Confirm and finish    | **Continue with all selected skills** or **Review individual skills**          | Reviewing lets you inspect selected packages and uncheck skills, which adds an exclusion while keeping the broad rule        |

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:

```markdown
<!-- 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.

### 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.

```json
{
  "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                  | Meaning                                                      |
| ------------------------ | ------------------------------------------------------------ |
| `"*"`                    | Every skill from every installed package                     |
| `"@tanstack/*"`          | Every skill from packages in the `@tanstack` scope           |
| `"@tanstack/ai"`         | Every skill shipped by `@tanstack/ai`, including future ones |
| `"@tanstack/ai#ai-core"` | One specific skill                                           |

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    | `intent.skills` value | Effect                                                                                                                                                                              |
| -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Absent   | No key                | 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    | `[]`                  | No package is surfaced                                                                                                                                                              |
| Wildcard | `["*"]`               | 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:

**pnpm**

```bash
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
```

**npm**

```bash
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**

```bash
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
```

**bun**

```bash
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`.

| Pattern                     | Excludes                                               |
| --------------------------- | ------------------------------------------------------ |
| `@scope/pkg`                | The whole package                                      |
| `@scope/pkg#*`              | The whole package (shortcut form)                      |
| `@scope/pkg#search-params`  | One skill in one package                               |
| `@scope/pkg#experimental-*` | Every skill in one package whose name matches the glob |
| `_#experimental-_`          | Matching skills across every package                   |
| `@tanstack/*devtools*`      | 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](https://tanstack.com/intent/latest/docs/concepts/trust-model) and [Configuration](https://tanstack.com/intent/latest/docs/concepts/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`:

**pnpm**

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

**npm**

```bash
npx @tanstack/intent@latest install --map
```

**yarn**

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

**bun**

```bash
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.

```yaml
<!-- 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.

### 6\. 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**

```bash
pnpm dlx @tanstack/intent@latest hooks install
```

**npm**

```bash
npx @tanstack/intent@latest hooks install
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest hooks install
```

**bun**

```bash
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`.

| Agent                      | Project scope                                       | User scope                    | Enforcement                                                                                                |
| -------------------------- | --------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Claude Code                | `.claude/settings.json`                             | `~/.claude/settings.json`     | Session-start catalog plus edit gate                                                                       |
| Codex                      | `.codex/hooks.json`                                 | `~/.codex/hooks.json`         | Session-start catalog plus edit gate. Codex asks you to review and trust non-managed hooks before they run |
| GitHub Copilot CLI         | Guidance only via `.github/copilot-instructions.md` | `~/.copilot/hooks/hooks.json` | Session-start catalog plus edit gate in user scope only                                                    |
| Cursor                     | Guidance only                                       | Guidance only                 | No blocking hook. Uses `AGENTS.md` or Cursor rules                                                         |
| Generic `AGENTS.md` agents | Guidance only                                       | Guidance only                 | No blocking hook. Uses the `intent-skills` block                                                           |

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

**pnpm**

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

**npm**

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

**yarn**

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

**bun**

```bash
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.
  

### 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**

```bash
pnpm dlx @tanstack/intent@latest list
```

**npm**

```bash
npx @tanstack/intent@latest list
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest list
```

**bun**

```bash
bunx @tanstack/intent@latest list
```
| Flag            | Effect                                                                                                                                                                       |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`        | Machine-readable output                                                                                                                                                      |
| `--global`      | Include globally installed packages alongside local ones                                                                                                                     |
| `--global-only` | Ignore local packages and scan only globals                                                                                                                                  |
| `--show-hidden` | 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 |
| `--no-notices`  | Suppress non-critical notices on stderr                                                                                                                                      |

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

```bash
pnpm dlx @tanstack/intent@latest load @tanstack/ai#ai-core
```

**npm**

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

**yarn**

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

**bun**

```bash
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.

| Flag                           | Effect                                                                              |
| ------------------------------ | ----------------------------------------------------------------------------------- |
| `--path`                       | Print the resolved skill file path instead of the content, for debugging            |
| `--json`                       | Print structured JSON with metadata and content                                     |
| `--exclude <pattern>`          | Skip package names matching a glob for this call only. Can be passed more than once |
| `--global` and `--global-only` | 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:

**pnpm**

```bash
pnpm dlx @tanstack/intent@latest meta
```

**npm**

```bash
npx @tanstack/intent@latest meta
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest meta
```

**bun**

```bash
bunx @tanstack/intent@latest meta
```

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

**pnpm**

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

**npm**

```bash
npx @tanstack/intent@latest meta <name>
```

**yarn**

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

**bun**

```bash
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.

### 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                      | Instead of                         |
| ----------------------------------------- | ---------------------------------- |
| `chat()`                                  | `streamText()`                     |
| `openaiText()` from `@tanstack/ai-openai` | `createOpenAI()`                   |
| `toServerSentEventsResponse()`            | Manual server-sent events wiring   |
| Middleware for lifecycle events           | An `onFinish` callback on `chat()` |

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

### 9\. Keep skills current

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

**pnpm**

```bash
pnpm update @tanstack/ai
```

**npm**

```bash
npm update @tanstack/ai
```

**yarn**

```bash
yarn up @tanstack/ai
```

**bun**

```bash
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**

```bash
pnpm dlx @tanstack/intent@latest stale
```

**npm**

```bash
npx @tanstack/intent@latest stale
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest stale
```

**bun**

```bash
bunx @tanstack/intent@latest stale
```

Update notifications for changed skill instructions are not available yet.

### Use 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:

```plaintext
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.

## Maintainer 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**

```bash
pnpm add -D @tanstack/intent
```

**npm**

```bash
npm i -D @tanstack/intent
```

**yarn**

```bash
yarn add -D @tanstack/intent
```

**bun**

```bash
bun add -d @tanstack/intent
```

### 1\. Scaffold skills with your agent

**pnpm**

```bash
pnpm dlx @tanstack/intent@latest scaffold
```

**npm**

```bash
npx @tanstack/intent@latest scaffold
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest scaffold
```

**bun**

```bash
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.

| Phase            | What happens                                                                                                                                        | Artifacts produced                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Domain discovery | Scans your documentation, source code, and GitHub issues, then interviews you to surface implicit knowledge and common failure modes                | `domain_map.yaml`, `skill_spec.md` |
| Tree generation  | Designs a skill taxonomy from the domain map and creates a hierarchical structure                                                                   | `skill_tree.yaml`                  |
| Skill generation | Writes a complete `SKILL.md` for each skill, including patterns, failure modes, and API references, then validates against the Intent specification | `skills/<name>/SKILL.md`           |

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.

### 2\. Validate before publishing

**pnpm**

```bash
pnpm dlx @tanstack/intent@latest validate
```

**npm**

```bash
npx @tanstack/intent@latest validate
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest validate
```

**bun**

```bash
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.

| Category        | Checks                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Skill structure | 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 |
| Intent metadata | Intent-specific scalars (`type`, `library`, `library_version`, `framework`) live under `metadata`, and framework skills have a `requires` array                                      |
| Artifacts       | Required artifact files exist and are non-empty, and YAML artifacts parse successfully                                                                                               |

### 3\. 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.

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

### 4\. Configure your package for publishing

Two helper commands prepare your package to ship skills:

**pnpm**

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

**npm**

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

**yarn**

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

**bun**

```bash
bunx @tanstack/intent@latest edit-package-json
bunx @tanstack/intent@latest setup
```
| Command             | What it does                                                                                                                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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 |
| `setup`             | Copies `check-skills.yml` into `.github/workflows/` for automated validation and staleness checking                                                                                                                                                                                                                |

`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.

### 5\. Ship skills with your package

Skills publish inside your npm package with no extra step:

```bash
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.

### 6\. Track staleness against source docs

**pnpm**

```bash
pnpm dlx @tanstack/intent@latest stale
```

**npm**

```bash
npx @tanstack/intent@latest stale
```

**yarn**

```bash
yarn dlx @tanstack/intent@latest stale
```

**bun**

```bash
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.

| Signal                   | Meaning                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Version drift            | A skill targets an older library version than the one currently installed          |
| New sources              | Sources declared in frontmatter that weren't tracked before                        |
| Artifact drift           | `_artifacts` entries no longer match the generated skills                          |
| Missing package coverage | Public workspace packages not represented by generated skills or artifact coverage |

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.

```yaml
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.

## 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.

|                          | TanStack Intent                                                                                                                              | AI SDK                                                                                                                       |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Install                  | `npx @tanstack/intent@latest install`, plus optional discovery skills via `npx skills add TanStack/ai`                                       | `npx skills add vercel/ai`                                                                                                   |
| Version-matched guidance | `SKILL.md` files inside each package that ships them                                                                                         | Full docs and source bundled at `node_modules/ai/docs/` and `node_modules/ai/src/`                                           |
| Project config           | `intent-skills` block in `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md`, plus an allowlist in `package.json` | Skill installed into the agent's skills directory, such as `.claude/skills` or `.codex/skills`                               |
| Enforcement              | Optional hooks that gate edits until a skill is loaded                                                                                       | Progressive disclosure. The agent loads the skill's name and description at startup and pulls full instructions in on demand |
| Migration help           | `tanstack-ai-migration` skill for porting from the AI SDK                                                                                    | Not applicable                                                                                                               |

Both use the open [Agent Skills](https://agentskills.io/) 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](https://ai-sdk.dev/docs/getting-started/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](https://vercel.com/kb/guide/deploy-a-tanstack-start-app-to-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

### `intent 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.

### `intent 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.

### 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](https://tanstack.com/intent/latest/docs/overview)
  
- [TanStack Intent Quick Start for Consumers](https://tanstack.com/intent/latest/docs/getting-started/quick-start-consumers)
  
- [TanStack Intent Quick Start for Maintainers](https://tanstack.com/intent/latest/docs/getting-started/quick-start-maintainers)
  
- [TanStack Intent CLI reference](https://tanstack.com/intent/latest/docs/cli/intent-install)
  
- [TanStack Intent trust model](https://tanstack.com/intent/latest/docs/concepts/trust-model)
  
- [Agent Skills registry](https://tanstack.com/intent/registry)
  
- [TanStack Intent in the TanStack AI docs](https://tanstack.com/ai/latest/docs/getting-started/agent-skills)
  
- [Getting Started with Coding Agents in the AI SDK docs](https://ai-sdk.dev/docs/getting-started/coding-agents)
  
- [TanStack Start on Vercel](https://vercel.com/docs/frameworks/full-stack/tanstack-start)