--- 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: /kb/guide/using-tanstack-intent-to-ship-and-consume-agent-skills canonical_url: "https://vercel.com/kb/guide/using-tanstack-intent-to-ship-and-consume-agent-skills" last_updated: 2026-07-16 authors: Ben Sabic related: - /docs/frameworks/full-stack/tanstack-start install_vercel_plugin: npx plugins add vercel/vercel-plugin --- AI coding agents often suggest outdated or incorrect patterns for a library because their training data lags behind the latest releases. TanStack Intent is a CLI for shipping and consuming Agent Skills as package artifacts: markdown documents that teach AI coding agents how to use your library correctly. This guide walks you through installing Intent with `intent install`, discovering skills from your dependencies with `intent list`, and loading a specific skill into your agent with `intent load`. You'll add explicit task-to-skill mappings so your agent selects the right skill unambiguously, and learn how to extend the same workflow to author and ship skills from a library you maintain. > TanStack Intent is in **alpha** at the time of writing. The API may change before a stable release. ## How it works Agent skills shipped with Intent are markdown documents that teach AI coding agents how to use a library correctly. Intent versions them with your releases, ships them inside npm packages, and helps agents load them automatically when working on matching tasks. 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, controlled by `--global` (include both local and global) or `--global-only` (ignore local). When both are scanned, local packages take precedence. The model has two sides: - **Consumers** install libraries that ship skills, then point their agent at the Intent CLI so the agent can list and load skills on demand. - **Maintainers** author skills in their library repo, validate them, and publish them as part of the same npm release as their code. Because skills live inside the package, the skill's version always matches the library's installed version. ## Prerequisites - Node.js and a package manager (npm, pnpm, Yarn, or Bun). - An AI coding agent that reads project-level config files such as `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`. - For the consumer workflow, at least one installed dependency that ships Intent skills. `list` and `load` won't return useful output without one. ## Consumer workflow If you're using a library that ships Intent skills, the consumer workflow automatically loads those skills for your agent. You'll run `intent install` once to add guidance to your agent config, then your agent uses `intent list` and `intent load` on demand as it works through tasks in your codebase. ### 1\. Install `@tanstack/intent` From the root of your project, run: `npx @tanstack/intent@latest install` Examples use `npx` for npm projects. In pnpm, Yarn, or Bun projects, use the matching runner: `pnpm dlx`, `yarn dlx`, or `bunx`. This creates or updates an `intent-skills` guidance block. It checks for existing `intent-skills` guidance in your config files (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and similar), writes lightweight instructions for skill discovery and loading, preserves content outside the managed block, and verifies the managed block before reporting success. The block Intent writes looks like this: `` ## Skill Loading Before substantial work: - Skill check: run `pnpm dlx @tanstack/intent@latest list`, or use skills already listed in context. - Skill guidance: if one local skill clearly matches the task, run `pnpm dlx @tanstack/intent@latest load #` and follow the returned `SKILL.md`. - 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 the package manager when generating this block, so the runner may be `npx`, `pnpm dlx`, `yarn dlx`, or `bunx`. ### 2\. List available skills To see every skill discoverable from your installed packages, run: `npx @tanstack/intent@latest list` Use `--json` for machine-readable output: `npx @tanstack/intent@latest list --json` Global package scanning is opt-in. Use `--global` to include globally installed packages alongside local ones, or `--global-only` to ignore local packages entirely: `npx @tanstack/intent@latest list --global npx @tanstack/intent@latest list --global-only` When both local and global packages are scanned, the local version takes precedence. ### 3\. Load a skill manually To print a specific skill to stdout, use the `package#skill` syntax: `npx @tanstack/intent@latest load @tanstack/react-query#core` This prints the skill content for the installed package version. In normal use, your agent runs this command itself when it identifies a matching skill, so you don't need to load skills by hand. ### 4\. Opt in to explicit task-to-skill mappings By default, Intent writes general loading guidance 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 the `--map` flag: `npx @tanstack/intent@latest install --map` ### 5\. Keep skills up to date Skills are versioned with library releases, so updating a library updates its skills: `npm update @trpc/tanstack-react-query` To check whether any installed skills reference outdated source documentation, run: `npx @tanstack/intent@latest stale` ### 6\. Submit feedback (optional) After your agent uses a skill, you can collect structured feedback for the maintainer(s): `npx @tanstack/intent@latest meta feedback-collection` This provides you with a skill that helps your agent collect structured feedback on gaps, errors, and improvements. You can then share this with the maintainer(s). ## Maintainer workflow If you maintain an npm package, the maintainer workflow covers authoring, validating, and shipping packages as part of your release. You'll scaffold skills with your agent's help, wire validation into CI to block malformed skill releases, and track staleness when source docs drift. ### Scaffold a skill `npx @tanstack/intent@latest scaffold` This prints a phased prompt that guides your agent through domain discovery, tree generation, and skill authoring, with stop gates between phases so you can review each one before moving on. The command itself doesn't create files. Your agent writes them based on the prompt. ### Validate before publishing `npx @tanstack/intent@latest validate` This enforces `SKILL.md` format rules and packaging requirements before publishing. Wire it into your CI so a malformed skill blocks a release the same way a failing test would. ### Prepare your package for publishing Two helper commands wire your package up for shipping skills: `# Update package.json with the required fields for skill discovery npx @tanstack/intent@latest edit-package-json # Copy the CI workflow template into your repo npx @tanstack/intent@latest setup` `edit-package-json` updates your package.json with the fields Intent needs to ship and discover skills, including the `tanstack-intent` keyword (used for package detection and registry discovery) and `files` array entries for `skills/`. In single-package repos, it also adds `!skills/_artifacts` so artifacts don't end up in the published tarball. In monorepos, it skips that exclusion, since artifacts live at the repo root. `setup` copies `check-skills.yml` into `.github/workflows/` for automated validation and staleness checking. It won't overwrite existing workflow files. To pick up a newer template, delete the old generated file first and rerun `setup`. If your repo still has an older generated `validate-skills.yml`, remove it once you've adopted `check-skills.yml`, since PR validation now runs from the latter. ### Track staleness against source docs `npx @tanstack/intent@latest stale` This flags three kinds of drift: - Skills whose declared source docs have changed - Generated skills that have drifted from their `_artifacts` - Public workspace packages that don't yet have skill coverage. Running it in CI gives you a failing check when any of those go out of sync, so skill reviews become part of your release checklist, like linting and tests. ### Other CLI commands The Intent CLI also exposes `intent meta` for listing bundled meta-skills or printing a specific one, such as `meta feedback-collection`. For the full surface of commands and flags, see the [TanStack Intent docs](https://tanstack.com/intent/latest/docs/overview). ## Using Intent with TanStack Start on Vercel Intent is framework-agnostic. It works on any project with installed npm dependencies and an agent that reads a config file. If you're building a [TanStack Start app deployed on Vercel](https://vercel.com/docs/frameworks/full-stack/tanstack-start), Intent fits naturally into your local development loop: - Run `npx @tanstack/intent@latest install` once in your project root. - Commit the `AGENTS.md` (or equivalent) file so the skill-loading guidance travels with your repo. - Skills live with your installed packages and are read on demand by your agent when it invokes `intent load`. Nothing about Intent runs at build time or affects your Vercel deployment output. ## Troubleshooting ### `intent install` didn't update my config file Intent only touches managed blocks, meaning content between `` and ``. If you renamed or removed those markers, Intent treats the file as not having a block and falls back to the default target (`AGENTS.md`). Check whether the markers are intact, or rerun `install` and let Intent recreate the block. ### My agent isn't loading skills The `intent-skills` block is guidance only. The agent has to act on it. Confirm that: - The config file is one your agent actually reads (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and similar). - The block is present and well-formed. - `npx @tanstack/intent@latest list` returns at least one skill. If it's empty, none of your installed packages ship Intent skills yet. ### `intent list` finds nothing Intent scans your project's installed dependencies for packages that declare skills. If you're working in a monorepo, run `list` from the workspace root rather than an individual package directory. To include globally installed packages, add `--global`. To scan only globals, use `--global-only`. ## 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 Skills Registry](https://tanstack.com/intent/registry) - [TanStack Intent CLI reference](https://tanstack.com/intent/latest/docs/cli/intent-install) - [TanStack Start on Vercel](https://vercel.com/docs/frameworks/full-stack/tanstack-start) * * * ### Learn about TanStack Hotkeys