TanStack
Intent
Getting Started

Overview

@tanstack/intent is a CLI for shipping and consuming Agent Skills as package artifacts.

Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases and ships them inside npm packages. It discovers skills from project and workspace dependencies, then provides commands and guidance for loading them.

What Intent does

Intent provides tooling for two workflows:

For consumers:

  • Discover skills from your project and workspace dependencies
  • Control which packages' skills are surfaced with an allowlist
  • Add lightweight skill loading guidance to your agent config
  • Add session catalogs and edit gates for supported agents
  • Use skills packaged with installed library versions

For maintainers (library teams):

  • Add a persistent skill-authoring and review procedure to repository instructions
  • Create or update focused skill guidance with an existing coding agent
  • Record source-aware review outcomes as the library changes
  • Validate SKILL.md format and packaging
  • Ship skills in the same release pipeline as code
  • Review version, source, artifact, and package coverage signals

Keep the workflow boundaries clear

StageWho runs itResult
Maintainer enablementLibrary maintainermaintainer setup creates missing records and installs persistent authoring instructions.
Authoring and maintenanceLibrary maintainer and coding agentmeta generate-skill guides a focused batch; maintainer review records evidence-backed outcomes for later source changes.
Package publishingLibrary release processmaintainer sync updates package and selected repository exports; setup optionally adds CI.
Consumer setupDeveloper using the published libraryConsumer install configures permitted skill sources and skill-loading guidance; list and load use skills from installed dependencies.

Note

Maintainer installation and consumer installation write separate managed guidance blocks. Neither command publishes a package or installs a dependency.

How it works

Discovery and installation

shell
npx @tanstack/intent@latest list

Scans the current project's installed dependencies for intent-enabled packages, including node_modules, workspace dependencies, and Yarn PnP projects without node_modules. You can narrow which packages are surfaced with package.json#intent.skills. See the Trust model and Configuration for how the allowlist works. Global package scanning is explicit; pass --global to include global packages or --global-only to ignore local packages. When both local and global packages are scanned, local packages take precedence.

shell
npx @tanstack/intent@latest install

Creates or updates lightweight intent-skills guidance in your config files (AGENTS.md, CLAUDE.md, .cursorrules, etc.). Existing guidance is updated in place; otherwise AGENTS.md is the default target. Pass --map to opt in to explicit task-to-skill mappings.

shell
npx @tanstack/intent@latest hooks install

Installs session catalogs and edit gates for supported agents. Project-scoped hooks are available for Claude Code and Codex. GitHub Copilot CLI project guidance can live in .github/copilot-instructions.md, while blocking hooks are user-scoped. Cursor and generic AGENTS.md agents use guidance only. See intent hooks for what hooks can observe.

shell
npx @tanstack/intent@latest load @tanstack/query#fetching

Loads the matching SKILL.md content for the installed package version. Pass --path when you need the resolved skill file path for debugging.

Maintainer authoring and review

shell
npx @tanstack/intent@latest maintainer setup

Creates missing planning records and installs the authoring procedure in repository instructions. It explains the distribution choice and remembers selected public skills or an opt-out. Skills stay in their owning packages. See the maintainer quick start.

Use maintainer add to create or register an agreed skill, then author its guidance and task evidence with your coding agent. During later library work:

shell
npx @tanstack/intent@latest maintainer status
npx @tanstack/intent@latest maintainer sync
npx @tanstack/intent@latest maintainer review --json

The commands identify work, align generated metadata, and prepare source-review evidence. Record justified outcomes with maintainer review --record <report.json> and finish with maintainer check. Content changes reopen review. The maintainer command reference covers the full workflow, package ownership, and consumer installer choices. Full-library research remains available through the meta-skills when requested.

Staleness tracking

shell
npx @tanstack/intent@latest stale

Reports version drift and source, artifact, or package coverage signals that may require skill review. Flagged text reports and generated review PR prompts route your agent to the same focused authoring procedure. The agent checks the source evidence before deciding whether guidance needs to change.

Edit on GitHub
Quick Start (Consumers)