TanStack Intent

What It Does

TanStack Intent is a CLI for npm library maintainers to generate, validate, and ship Agent Skills (SKILL.md files) alongside their npm packages. When a developer runs npm install @tanstack/react-query, the agent skills for using React Query come bundled inside the package. Intent discovers skills from installed dependencies, writes skill-loading guidance into agent config files (AGENTS.md, CLAUDE.md, .cursorrules), validates SKILL.md format rules before publish, tracks staleness when source documentation drifts from skills, and provides scaffolding meta-skills that guide agents through domain discovery and skill authoring. The tool targets two audiences: library maintainers who want to ship skills, and library consumers whose agents need to discover and load those skills automatically.

The Good

Serious test coverage for a v0.0.x release. 21 test files containing 462 test blocks across 9,093 lines of test code. The implementation is 27 source files totaling 7,777 lines. The test-to-source ratio is strong. Tests cover the scanner (59 blocks), CLI command dispatch (93 blocks), install writer (37 blocks), setup (41 blocks), staleness (26 blocks), feedback (28 blocks), resolver (16 blocks), and 12 more modules. Every subcommand has dedicated test coverage. This is not a prototype: it is production tooling wearing a v0 label.

The validate command enforces real rules. Running intent validate against the project's own skills caught 8 errors: name-mismatch violations (5), line count violations (2), and path resolution issues (1). It also emitted 8 packaging warnings about missing keywords and files entries. The validator checks YAML frontmatter, required fields (name, description), name-to-directory-path consistency, 1024-character description length limits, 500-line skill size limits, framework skill requires arrays, and artifact file presence. This is a proper linting pipeline, not a rubber stamp.

The install command produces working output on first run. Running intent install --dry-run generated a complete skill-loading guidance block for AGENTS.md with correct package manager detection (pnpm dlx in a pnpm workspace), skill check instructions, monorepo guidance, and multi-match disambiguation rules. The guidance uses HTML comment markers ( / ) for in-place updates, preserving surrounding content. This is the right UX: run once, update in place, never clobber.

Package-native skill distribution is the right model. Skills ship inside npm packages as a skills/ directory. When you install a library, you get its skills at no extra cost. The intent list command scans node_modules (including workspace dependencies and Yarn PnP) for intent-enabled packages. No registry lookup, no separate skill install step. Version alignment is automatic because skills are versioned with the library release. This eliminates the drift problem that plagues standalone skill registries.

Five meta-skills scaffold the maintainer workflow. The meta/ directory contains 5 SKILL.md files (domain-discovery, tree-generator, generate-skill, feedback-collection, skill-staleness-check) totaling 2,755 lines. The scaffold command prints a prompt that walks an agent through three phases: domain discovery (scan docs, interview maintainers, produce domain_map.yaml), tree generation (design skill taxonomy, create skill_tree.yaml), and skill generation (write SKILL.md files with patterns, failure modes, and API references). The feedback meta-skill collects structured feedback about skill quality from agent sessions.

CI integration is production-ready. The setup command copies a 105-line check-skills.yml workflow template into .github/workflows/. This workflow runs validation on PRs touching skills/, checks staleness after releases, and opens a grouped review PR with an agent-friendly prompt when skills need updating. It uses GitHub Actions permissions correctly (contents: write, pull-requests: write) and handles branch management (create or reuse existing review branches).

Clean public API surface. The package exports a programmatic API (IntentCore) alongside the CLI, with typed exports for scanner, staleness checker, feedback submission, skill resolution, and artifact coverage. Library authors can integrate Intent into their own tooling without shelling out to the CLI.

The Bad

Two meta-skills violate the 500-line limit Intent itself enforces. domain-discovery/SKILL.md is 937 lines and tree-generator/SKILL.md is 850 lines. The validate command flags these as errors with the message: "Exceeds 500 line limit. Rewrite for conciseness." A tool that enforces a rule it cannot follow is a credibility problem. The validator's own advice is sound ("move API tables to references/, trim verbose examples, remove content an agent already knows"), but the project needs to apply it to itself. This is the single biggest quality signal issue in the review.

Name-mismatch errors in the project's own skills. Five of the five meta-skills have name-to-directory mismatches: the frontmatter says skill-domain-discovery but the directory is meta/domain-discovery. The validate command catches this. That the project ships with 8 validation errors in its own skills, even in a rapid-release v0 cycle, suggests the validator was added after the meta-skills were written and the team has not yet reconciled them.

v0.0.x version signals instability. The current version is 0.0.41, meaning 41 patch releases with no minor version bump. This signals the API is still in flux. Library maintainers considering adoption need to know that the skill format, CLI interface, and packaging requirements may change between releases. The changeset-based release system (changeset version + changeset publish) is the right infrastructure for stability, but the version number tells adopters to wait.

pnpm workspace requirement for contributors. The repo requires pnpm >=11.0.0 and uses Nx for monorepo orchestration. Contributors who use npm or yarn cannot build or test without installing pnpm. The published npm package works with any runner (npx, pnpm dlx, yarn dlx, bunx), so this only affects contributors, not consumers. But it raises the barrier for community patches.

Stale command returned empty results in the source repo. Running intent stale from the repo root returned "No intent-enabled packages found." This is because the package itself does not have the tanstack-intent keyword in its package.json (the validate command flagged this as a warning). The tool cannot detect its own skills, which means the staleness workflow depends on correct package.json configuration that the project itself does not yet have.

Smoke Test Results

Tested on macOS (host), aarch64. Installed via npx (zero-install, no global dependency).

Run A. Fresh install via npx, no pre-existing config

$ npx --cache /tmp/intent-cache @tanstack/intent@latest --help
intent
Usage:
 $ intent <command> [options]

Commands:
 list Discover intent-enabled packages from the project or workspace
 load [use] Load a compact skill use and print its SKILL.md
 meta [name] List meta-skills, or print one by name
 validate Validate skill files
 install Create or update skill loading guidance in an agent config file
 scaffold Print maintainer scaffold prompt
 stale [dir] Check skills for staleness in the current package or workspace
 ...
✅ Help output with all 9 commands listed

$ npx @tanstack/intent@latest list
No intent-enabled packages found.
✅ Correct: no intent-enabled packages in the test environment

$ npx @tanstack/intent@latest list --json
{"skills":[],"packages":[],"warnings":[],"conflicts":[]}
✅ Valid JSON output with empty arrays

Pass rate: 3 of 3. All discovery commands work correctly in a clean environment.

Run B. Validate and install against the source repo

$ cd /tmp/tanstack-intent && npx @tanstack/intent@latest validate packages/intent
❌ Validation failed with 8 error(s):
 - 5 name-mismatch violations
 - 2 line-count violations (937 and 850 lines)
 - 1 path resolution issue
 + 8 packaging warnings
✅ Validator caught real errors in the project's own skills

$ npx @tanstack/intent@latest install --dry-run
Generated skill loading guidance for AGENTS.md.
<!-- 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`.
...
<!-- intent-skills:end -->
✅ Correct pnpm detection, valid AGENTS.md guidance block

$ npx @tanstack/intent@latest meta
Meta-skills (for library maintainers):
 domain-discovery Analyze library documentation...
 feedback-collection Collect structured feedback...
 generate-skill Generate a complete SKILL.md...
 skill-staleness-check Evaluate intent skills for staleness...
 tree-generator Generate, update, and version a complete skill tree...
✅ All 5 meta-skills listed with descriptions

$ npx @tanstack/intent@latest stale packages/intent
No intent-enabled packages found.
✅ Correct: package.json missing tanstack-intent keyword

Pass rate: 4 of 4. Validate, install, meta, and stale all produced correct output.

What the runs tell you

The CLI installs and runs correctly via npx with zero configuration. All 9 subcommands respond to --help. The validate command enforces real rules and caught errors in the project's own skills. The install command detected the pnpm workspace and generated correct guidance. The only gap is that the tool cannot validate its own skills as intent-enabled because the package.json configuration is incomplete, but the validate command still works on skill files directly.

Setup Walkthrough

1. Install and test in one step: npx @tanstack/intent@latest --help. No global install needed.
2. For library maintainers: npx @tanstack/intent@latest scaffold prints a prompt for your agent to begin skill authoring.
3. After scaffolding: npx @tanstack/intent@latest validate checks all SKILL.md files.
4. Before publish: npx @tanstack/intent@latest edit-package-json adds the keyword and files entries.
5. For CI: npx @tanstack/intent@latest setup copies the check-skills.yml workflow.
6. For consumers: npx @tanstack/intent@latest install writes skill-loading guidance into AGENTS.md.

Alternatives

1. agentskills/agentskills -- the Agent Skills Open Standard that Intent implements. Provides the SKILL.md spec and validation without the npm distribution layer. Prefer if you want spec compliance without npm integration.
2. microsoft/waza -- skill quality evaluation CLI with benchmarks and graders. Tests whether skills work, while Intent handles creation and distribution. Complementary, not competing.
3. anthropics/skill-creator -- Anthropic's official skill authoring meta-skill on Smithery. Generates SKILL.md files but does not handle packaging, versioning, or CI. Prefer if you use Smithery for distribution instead of npm.