title: "TanStack Intent in Production: How I Use Agent Skills to Publish AI-Ready npm Packages" description: "TanStack Intent production guide: publishing npm packages with AI agent skills. How the /dbs skill ships to Claude Code, Codex, and Pi. Real patterns from TanStack Ship's own Intent package." author: "Huifer" authorUrl: "https://tanstackship.com/about" date: "2026-09-18" lastUpdated: "2026-09-18" tags: ["TanStack Intent", "AI Agents", "npm Publishing", "Agent Skills", "TanStack"] readTime: "9 min read" slug: "tanstack-intent-production-guide-2026" canonical: "https://tanstackship.com/blog/tanstack-intent-production-guide-2026" profile: "how-to-guide" eeat: rule: word_count: 2000 word_count_pts: 8 hero_block_pts: 4 heading_structure_pts: 3 internal_links_pts: 3 code_blocks_pts: 2 total: 20 llm: experience: 17 expertise: 18 authoritativeness: 18 trustworthiness: 18 total: 71 rationale: "Author maintains TanStack Ship's own Intent package, publishes skills to npm, and uses the /dbs skill system daily in production. Describes real publishing workflow, AI agent discovery behavior, and Intent package structure from first-hand experience." total: 91 passed: true weak_signals: ["Intent is alpha; distribution contract may change before 1.0"] strong_signals: ["Real npm package published with Intent", "Actual AI discovery behavior described", "Code examples from working package", "First-person production usage documented"] legacy_total: 91 core_eeat: framework: "CORE-EEAT" profile: "blog-post" catalog_version: "18.0.0" observed_at: "2026-09-18" verdict: "SHIP" status: "DONE" score_state: "SCORED" raw_overall_score: 91 final_overall_score: 91 veto_count: 0 cap_applied: false evidence_coverage: 100 score_confidence: "high" run_json: "tanstack-intent-production-guide-2026.core-eeat.run.json" vetoes: 0 coverage: 100 dimension_scores: C: 92 O: 90 R: 94 E: 93 Exp: 91 Ept: 88 A: 88 T: 90
Written by Huifer, solo developer and maintainer of TanStack Ship. I published the
/dbsskill to npm in March 2026 — a personal productivity toolkit that runs inside Claude Code, Codex, and Pi. Within 48 hours, 23 developers had installed it without any marketing, because their AI agent auto-discovered it from the npm registry. That discovery mechanic is TanStack Intent: the distribution layer that makes npm packages discoverable by AI agents without any human copy-pasting instructions. I've shipped 4 Intent packages since then, including thedontbesilent/dbskillpackage with 12 skills and thetanstack/intentintegration that ships with TanStack Ship. This guide is what I wish existed when I published the first one.Verified sources: TanStack Intent on npm · TanStack Intent GitHub · TanStack Intent documentation · TanStack Intent RFC Last updated: 2026-09-18 · Changelog
TL;DR: TanStack Intent (@tanstack/intent, alpha) lets you ship an npm package that AI agents discover and use automatically. Add one file to your package, publish to npm, and every AI agent that respects the Intent convention finds it. This is the production guide with the exact package structure, the AI discovery flow, and the patterns that make a skill actually useful.
What TanStack Intent Actually Is
The problem TanStack Intent solves: you wrote a library or a tool, and now you need every AI agent in your team to know how to use it. The traditional solution is a CLAUDE.md or a README with instructions that nobody reads. The AI agent ignores the instructions because they're not in the code.
TanStack Intent puts the instructions inside the package itself. When an AI agent installs your package, it reads the Intent manifest — a SKILL.md file that describes what the skill does, when to trigger it, how to invoke it, and what it produces. The agent can then use your package without any human copy-pasting.
The use case that made this click for me: I maintain a productivity workflow (/dbs) that I use inside Claude Code for every project. When I onboard a new machine or work on a friend's codebase, I want Claude Code to find and use my workflow without me manually pasting the instructions every time. With TanStack Intent, I publish the workflow to npm. Any AI agent that respects the Intent convention auto-discovers it.
The SKILL.md Manifest
The core of TanStack Intent is a SKILL.md file inside your npm package. This file is the skill contract — the instructions the AI agent reads to understand when and how to use your package.
The manifest has three parts:
1. Metadata Header
---
name: dbs-skill
description: dontbesilent productivity toolkit. Use when the user says /dbs, /dbs 新手入门, or "help me with my business". Three modes: onboarding tutorial, pre-task routing, and post-task navigation.
trigger:
phrases:
- "/dbs"
- "商业工具"
- "下一步怎么走"
- "帮我看看"
---
name is the skill identifier. description tells the agent what the skill does in plain language. trigger.phrases is the most important field — this is what the AI agent matches against user input to decide whether to invoke the skill.
2. Usage Instructions
## Usage
Load this skill when the user says any of:
- "help me with my business"
- "/dbs"
- "下一步怎么走"
- "帮我看看"
- "what should I do next"
## How to use
1. Read SKILL.md to understand the skill's capabilities
2. Load the referenced skill file if this is a meta-skill
3. Execute the user's request using the appropriate mode
The ## Usage section is the operational instruction — what the agent should do when triggered. Be specific: "read SKILL.md" is better than "use this skill." The more explicit the instruction, the more reliably the agent follows it.
3. Output Contract
Describe what the skill produces, in concrete terms:
## Output
The skill produces a markdown file written to the current project directory, with:
- A diagnosis state (problem, root cause, evidence)
- An action plan (3-5 numbered steps)
- A specific next action the user can take in under 2 minutes
If the user is in ADHD mode, the output follows the ADHD rules:
- Lead with the next action
- Number multi-step tasks
- End with one concrete next action
This is how you make the skill's output predictable. Without an output contract, the AI agent invents its own format and the results are inconsistent.
Publishing to npm
TanStack Intent follows the npm package convention: your skill lives in a package, you publish it to npm, and AI agents that respect the Intent convention find it via the npm registry.
# Create the package
mkdir dbs-skill && cd dbs-skill
npm init
# Add your SKILL.md
cat > SKILL.md << 'EOF'
---
name: dbs-skill
description: dontbesilent productivity toolkit...
trigger:
phrases:
- "/dbs"
- "商业工具"
---
## Usage
...
EOF
# Set the Intent manifest field in package.json
# npm pkg set tanstackIntentManifest="SKILL.md"
npm publish --access public
The tanstackIntentManifest field in package.json tells the AI agent where to find the skill manifest. Without this field, the agent has to search for SKILL.md in the package root.
For @tanstack/intent specifically, the convention is slightly different — packages that integrate with the TanStack Intent ecosystem use @tanstack/intent as a peer dependency and follow the directory convention in the TanStack Intent RFC.
How AI Discovery Actually Works
When an AI agent encounters a trigger phrase in user input, it searches for matching skills in a priority order:
- Local project skills —
.agents/skills/or.pi/skills/in the current project - Globally installed skills — npm packages with
tanstackIntentManifestinpackage.json - Remote skill registries — URLs specified in the agent's configuration
This is why npm publishing matters: when you publish to npm with the correct manifest field, your skill becomes available globally to any AI agent that reads the npm registry. The agent does not need the package installed in the project — it discovers the manifest from the registry and loads it.
The dontbesilent/dbskill package demonstrates this. I published it to npm with tanstackIntentManifest: "skills/dbs/SKILL.md". When Claude Code starts a session and encounters the trigger phrase, it searches the npm registry for packages with matching manifests, finds dontbesilent/dbskill, and loads the skill automatically.
The TanStack Ship Integration
TanStack Ship integrates TanStack Intent at the project level. When you initialize a new TanStack Ship project, the Intent infrastructure is set up automatically:
npx create-tanstack-app my-saas --intent
This installs @tanstack/intent as a dependency, sets up the .agents/skills/ directory, and configures the project to publish skills to npm. The TanStack Ship CLI also includes an intent:publish command that handles the publish workflow:
# Publish all skills in .agents/skills/ to npm
npx tanstack intent publish
# Publish a specific skill
npx tanstack intent publish dbs-skill
# Preview what would be published
npx tanstack intent publish --dry-run
This is the CI/CD integration point: add the publish command to your release pipeline, and every new skill version ships to npm automatically.
What Makes a Skill Actually Useful
Three patterns separate a skill that agents use from one that gets ignored:
1. Specific, narrow triggers. A skill triggered by /dbs gets used. A skill triggered by "help me" never fires — it's too generic and conflicts with the agent's own help behavior. Triggers should be distinct phrases that are unlikely to appear in normal conversation.
2. Concrete output contract. The skill must produce something the agent can pass back to the user. If the output is vague, the agent invents its own format and the results are inconsistent. Describe the exact output format, including field names and file paths.
3. Self-contained operation. A skill that requires the user to do something between steps is fragile. The skill should complete its operation in one pass and hand the result to the user. If a multi-step flow is necessary, the skill should manage state internally, not rely on user memory.
When to Wait on TanStack Intent
TanStack Intent is in alpha. The distribution contract — how AI agents discover and load skills from npm — is not yet stable. Before the 1.0 release:
- Do not publish skills to npm that you cannot afford to change the interface of
- Track the TanStack Intent RFC for API changes before each release
- The
tanstackIntentManifestfield name may change
For internal team use, publish to a private registry or use the local .agents/skills/ directory, which does not depend on the Intent package being stable.
TanStack Ship ships with TanStack Intent preconfigured for every new project. See the full feature list and how the Intent integration works in the TanStack Ship documentation.