Quick Start for Maintainers | TanStack Intent Docs

Get started scaffolding, validating, and shipping skills for your library.

Install

npm i -D @tanstack/intent

Or run commands without installing:

npx @tanstack/intent@latest scaffold

Warning

When using npx or bunx, always include @latest. Intent-enabled libraries ship a local intent binary shim, and without @latest, your package manager may resolve to that shim instead of the real CLI.

Initial Setup (With Agent)

1. Scaffold skills

Start the scaffolding process with your AI agent:

npx @tanstack/intent@latest scaffold

This prints a comprehensive prompt that walks you and your agent through three phases:

Phase 1: Domain Discovery

Scans your documentation, source code, and GitHub issues
Conducts an interactive interview to surface implicit knowledge
Produces domain_map.yaml and skill_spec.md artifacts

Phase 2: Tree Generation

Designs a skill taxonomy based on the domain map
Creates a hierarchical skill structure
Produces skill_tree.yaml artifact

Phase 3: Skill Generation

Writes complete SKILL.md files for each skill
Includes patterns, failure modes, and API references
Validates against the Intent specification

Note

This is a context-heavy process that involves domain discovery, GitHub issues analysis, and interactive maintainer interviews. The agent will scan your documentation, recent issues and discussions, and ask targeted questions to surface implicit knowledge and common failure modes. The more information you provide about your library's patterns, pitfalls, and real-world usage problems, the better the generated skills will be. Expect multiple rounds of refinement and regular context compaction before completion.

2. Validate skills

After scaffolding, validate that all SKILL.md files are well-formed:

npx @tanstack/intent@latest validate

This checks:

Valid YAML frontmatter in every SKILL.md
Required fields (name, description) are present
Skill names match their directory paths
Description length <= 1024 characters
Line count limits (500 lines max per skill)
Framework skills have a requires array
Artifact files exist and are non-empty

If any artifacts are present (domain_map.yaml, skill_spec.md, skill_tree.yaml), they must parse as valid YAML.

3. Commit skills and artifacts

Commit both generated skills and the artifacts used to create them:

skills/
  core/SKILL.md
  react/SKILL.md
  _artifacts/
    domain_map.yaml
    skill_spec.md
    skill_tree.yaml

Artifacts enforce a consistent skill structure across versions, making it easier to audit, refresh, or extend the skill set without starting from scratch.

Publish Configuration

4. Configure your package for publishing

Run these commands to prepare your package for skill publishing:

# Generate the bin shim that consumers use for discovery
npx @tanstack/intent@latest add-library-bin

# Update package.json with required fields
npx @tanstack/intent@latest edit-package-json

# Copy CI workflow templates (validate + stale checks)
npx @tanstack/intent@latest setup-github-actions

What these do:

add-library-bin creates bin/intent.js or bin/intent.mjs — a shim that lets consumers run npx your-package intent to access Intent CLI features
edit-package-json adds:
- intent field in package.json with version, repo, and docs metadata
- bin.intent entry pointing to the shim
- files array entries for skills/ and bin/
- For single packages: also adds !skills/_artifacts to exclude artifacts from npm
- For monorepos: skips the artifacts exclusion (artifacts live at repo root)
setup-github-actions copies workflow templates to .github/workflows/ for automated validation and staleness checking

5. Ship skills with your package

Skills ship inside your npm package. When you publish:

npm publish

Consumers who install your library automatically get the skills. They discover them with intent list and map them with intent install.

Version alignment:

Skills version with your library releases
Agents always load the skill matching the installed library version
No drift between code and guidance

Ongoing Maintenance (Manual or Agent-Assisted)

6. Set up CI workflows

After running setup-github-actions, you'll have three workflows in .github/workflows/:

validate-skills.yml (runs on PRs touching skills/)

Validates SKILL.md frontmatter and structure
Ensures files stay under 500 lines
Runs automatically on every pull request that modifies skills

check-skills.yml (runs on release or manual trigger)

Automatically detects stale skills after you publish a new release
Opens a review PR with an agent-friendly prompt
Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills

notify-intent.yml (runs on docs/source changes to main)

Sends a webhook to TanStack/intent when your docs or source change
Enables cross-library skill staleness tracking
Requires a fine-grained GitHub token (INTENT_NOTIFY_TOKEN) secret

7. Update stale skills

When you publish a new release, check-skills.yml automatically opens a PR flagging skills that need review.

Manually check which skills need updates with:

npx @tanstack/intent@latest stale

This detects:

Version drift — skill targets an older library version than currently installed
New sources — sources declared in frontmatter that weren't tracked before

To update stale skills:

Review the PR opened by check-skills.yml
Copy the agent prompt from the PR description
Paste it into Claude Code, Cursor, or your coding agent
The agent reads the stale skills and updates them based on library changes
Run npx @tanstack/intent@latest validate locally to verify
Commit and merge the PR

Note

Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt — your agent handles the actual updates.

Use --json output for CI integration or scripting.

8. Maintain and iterate

As your library evolves:

When APIs change: Update relevant SKILL.md files with new patterns
When docs change: Run intent stale to identify affected skills
When issues are filed: Check if the failure mode should be added to "Common Mistakes"
After major releases: Consider re-running domain discovery to catch new patterns

Tip

Create GitHub issue labels matching your skill names (skill:core, skill:react). When users file issues, tag them with the relevant skill label to track which areas need the most improvement.