Using TanStack Intent to ship and consume agent skills

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.

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

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

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.

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:

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

Intent detects the package manager when generating this block, so the runner may be npx, pnpm dlx, yarn dlx, or bunx.

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.

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.

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

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

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

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.

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.

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.

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.

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.

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.

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

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

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

• TanStack Intent overview
• TanStack Intent Quick Start for Consumers
• TanStack Intent Quick Start for Maintainers
• TanStack Intent Skills Registry
• TanStack Intent CLI reference
• TanStack Start on Vercel