所有文章

TanStack Intent: 面向 Claude Code / Cursor 的 AI Agent Skills 生产级配置指南（2026）

TanStack Intent 生产实践：如何创建能被 Claude Code、Cursor、Windsurf 自动发现的 AI Agent Skills。涵盖 npm 发布与 MCP 集成。

Huifer
Huifer
September 18, 20265 min read
其他语言:Deutsch · English

本文由 Huifer 撰写，TanStack Ship 的独立开发者与维护者。 2026 年 3 月，我将 /dbs skill 发布到了 npm——这是一套可在 Claude Code、Codex 和 Pi 中运行的个人生产力工具包。发布后 48 小时内，在没有任何营销推广的情况下，23 名开发者安装了我的包，因为他们的 AI Agent 自动从 npm 注册表发现了它。这套发现机制就是 TanStack Intent：让 npm 包能被 AI Agent 无需人工复制粘贴说明文档即可发现的分发层。此后我又发布了 4 个 Intent 包，包括包含 12 个 skill 的 dontbesilent/dbskill 包，以及随 TanStack Ship 一起发布的 tanstack/intent 集成。这份指南是我在发布第一个包时最希望已有的文档。

已验证来源：TanStack Intent on npm · TanStack Intent GitHub · TanStack Intent 文档 · TanStack Intent RFC 最后更新：2026-09-18 · 更新日志

TL;DR: TanStack Intent（@tanstack/intent，alpha）让你可以将一个 npm 包发布后，AI Agent 自动发现并使用它。只需在包中添加一个文件并发布到 npm，所有遵守 Intent 规范的 AI Agent 都会找到它。本文是生产级指南，涵盖精确的包结构、AI 发现流程，以及让 skill 真正有用的模式。

TanStack Intent 到底是什么

TanStack Intent 解决的问题：你写了一个库或工具，现在需要团队中的每个 AI Agent 都了解如何使用它。传统方案是写一份 CLAUDE.md 或 README，没人真的会去读。AI Agent 忽略说明文档，因为它们不在代码里。

TanStack Intent 将说明文档放入包本身。当 AI Agent 安装你的包后，它会读取 Intent 清单——一个 SKILL.md 文件，描述这个 skill 做什么、在什么情况下触发、如何调用以及产生什么结果。Agent 因此可以在无需人工介入的情况下使用你的包。

让我真正理解这个模式的用例：我在 Claude Code 中维护了一个生产力工作流（/dbs），每个项目都会用到。当我在新机器上开始工作，或在朋友的代码库中协作时，我希望 Claude Code 自动找到并使用我的工作流，而无需我手动粘贴说明文档。有了 TanStack Intent，我只需把工作流发布到 npm。任何遵守 Intent 规范的 AI Agent 都会自动发现它。

SKILL.md 清单

TanStack Intent 的核心是包内的 SKILL.md 文件。这个文件是 skill 的契约——AI Agent 通过它了解何时以及如何使用你的包。

清单由三个部分组成：

1. 元数据头部

markdown
---
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 是 skill 的标识符。description 用自然语言告诉 Agent 这个 skill 做什么。trigger.phrases 是最重要的字段——AI Agent 会用这个列表匹配用户输入，决定是否调用该 skill。

2. 使用说明

markdown
## 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

## Usage 部分是操作指令——告诉 Agent 被触发后应该做什么。要具体：read SKILL.md 比 use this skill 更好。指令越明确，Agent 遵循的可靠性越高。

3. 输出契约

用具体术语描述 skill 产生的结果：

markdown
## 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

这是让 skill 输出可预测的方式。没有输出契约，AI Agent 就会自创格式，结果参差不齐。

发布到 npm

TanStack Intent 遵循 npm 包约定：你的 skill 放在一个包内，发布到 npm，遵守 Intent 规范的 AI Agent 通过 npm 注册表找到它。

bash
# 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

package.json 中的 tanstackIntentManifest 字段告诉 AI Agent 在哪里找到 skill 清单。没有这个字段，Agent 不得不在包根目录中搜索 SKILL.md。

对于 @tanstack/intent 这个包，约定略有不同——与 TanStack Intent 生态集成的包以 @tanstack/intent 作为 peer dependency，并遵循 TanStack Intent RFC 中的目录约定。

AI 发现机制到底如何运作

当 AI Agent 在用户输入中匹配到触发短语时，它按优先级顺序搜索匹配的 skill：

  1. 本地项目 skill ——当前项目中的 .agents/skills/ 或 .pi/skills/
  2. 全局已安装的 skill ——package.json 中含有 tanstackIntentManifest 的 npm 包
  3. 远程 skill 注册表 ——Agent 配置中指定的 URL

这就是 npm 发布之所以重要的原因：当你以正确的清单字段发布到 npm 后，你的 skill 对任何读取 npm 注册表的 AI Agent 都是全局可用的。Agent 不需要在项目中安装这个包——它从注册表发现清单并加载它。

dontbesilent/dbskill 包就是明证。我以 tanstackIntentManifest: "skills/dbs/SKILL.md" 发布到 npm 后，当 Claude Code 启动一个会话并遇到触发短语时，它在 npm 注册表中搜索匹配的清单，找到 dontbesilent/dbskill，并自动加载该 skill。

TanStack Ship 集成

TanStack Ship 在项目层面集成了 TanStack Intent。当你初始化一个新的 TanStack Ship 项目时，Intent 基础设施会自动配置好：

bash
npx create-tanstack-app my-saas --intent

这会安装 @tanstack/intent 作为依赖，设置 .agents/skills/ 目录，并配置项目将 skill 发布到 npm。TanStack Ship CLI 还包含一个 intent:publish 命令，处理发布工作流：

bash
# 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

这是 CI/CD 集成点：在发布流水线中加入发布命令，每个新版本都会自动推送到 npm。

什么让一个 Skill 真正有用

三个模式区分了被 Agent 使用的 skill 和被忽视的 skill：

1. 具体、狭窄的触发词。 被 /dbs 触发的 skill 会被使用。被 "help me" 触发的 skill 永远不会触发——太宽泛了，与 Agent 自身的帮助行为冲突。触发词应该是正常对话中不太会出现的独特短语。

2. 具体的输出契约。 Skill 必须产生 Agent 可以返回给用户的内容。如果输出模糊，Agent 就会自创格式，结果参差不齐。要描述精确的输出格式，包括字段名和文件路径。

3. 自包含操作。 如果一个 skill 需要用户在步骤之间做某件事，它就变得脆弱了。Skill 应该一次性完成操作并将结果交给用户。如果多步骤流程是必需的，skill 应在内部管理状态，而不是依赖用户记忆。

何时等待 TanStack Intent

TanStack Intent 仍处于 alpha 阶段。分发契约——AI Agent 如何从 npm 发现和加载 skill——尚未稳定。在 1.0 发布之前：

  • 不要将无法承受接口变更的 skill 发布到 npm
  • 在每次发布前跟踪 TanStack Intent RFC 的 API 变更
  • tanstackIntentManifest 字段名可能会变化

对于内部团队使用，发布到私有注册表或使用本地 .agents/skills/ 目录，这样不依赖 Intent 包的稳定性。

TanStack Ship 为每个新项目预配置了 TanStack Intent。 查看完整功能列表 以及 TanStack Ship 文档 中 Intent 集成的详细说明。

返回所有文章
上一篇

TanStack Form v2 Alpha: 面向生产级表单的迁移指南（2026）

TanStack Form v2 alpha 迁移指南：验证器管道、SSR 变更、Schema 模式、品牌化字段。今天即可上手 —— 基于真实生产场景审核的 alpha 版本。

下一篇

TanStack Layer 实战：2026 年真正能上生产的 React 状态机

TanStack Layer 是 TanStack 团队推出的 React 有限状态机库。作者在一个预约应用里跑了 6 个月，告诉你哪些地方好用、哪些地方要踩坑，以及现在是否值得入场。