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#

How it works#

Discovery and installation#

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.

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.

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.

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#

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:

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#

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.