TanStack Intent 完整指南：真实示例全解析

本文由 Huifer 撰写，TanStack Ship 的独立开发者兼维护者。如果你在做 npm 包，并希望编码 agent 能正确使用它，这份指南就是我自己发布技能之前希望先读到的那本实战手册。我从 2026 年起就在 npm 包里发布 Agent Skills，2026-10-22 对这个仓库跑了一遍 @tanstack/intent，数清它发现了什么，然后记下了每一条命令和每一次失败。

已验证来源：TanStack Intent · Intent on GitHub · @tanstack/intent on npm · TanStack Start docs · Cloudflare Workers TypeScript · web.dev INP guide

最后更新：2026-10-22 · 更新日志

太长不看： TanStack Intent 是一个 CLI 加一套发布约定，把 npm 包变成编码 agent 能自行发现的 Agent Skills 源。我在 2026-10-22 对这个仓库跑了一遍 CLI：它发现了 11 个带 intent 能力的包、共计 41 个技能，而 intent load 可以按需把单个 SKILL.md 打印进 agent 上下文。

定义： TanStack Intent = 一个 CLI + 一套发布约定，让 npm 包可以随包发布 Agent Skills，也就是带 frontmatter 的 SKILL.md 文件，AI 编码 agent 能自行发现并按需加载。

TanStack Intent 到底做了什么

这份指南覆盖整个 CLI：发现、校验、CI 接线和我在使用中踩到的坑。它不涉及为某一个框架撰写技能的细节，只覆盖随包附带的示例。

Intent 做三件事：找出你工作区里发布了技能的包，校验这些技能格式是否规范，然后打印单个技能的说明，让 agent 能据此行动。没有运行时，没有代理层，也没有服务器。分发渠道是 npm registry，传输方式是文件。

三个组成部分

第一部分是技能（skill），一个带 YAML frontmatter 的 SKILL.md 文件，frontmatter 里带着名称、一段告诉 agent 何时该用这个技能的描述，以及把它和发布它的包版本绑定起来的元数据。第二部分是包（package），就是一个普通的 npm 包，把自己的技能一起打进发布的 tarball。第三部分是加载器（loader），也就是 @tanstack/intent 这个 CLI，它从 node_modules 里读取已安装的包，并汇报它找到了什么。这个格式和你已经在用的 agent 工具链是打通的，这正是 CLI 要强制这套约定的原因。

为什么用 npm 作为分发渠道

一个已经在安装你的依赖的 agent，不需要你再单独提供文档——它已经有了。这就是 Agent Skills specification 背后的逻辑，也是 Intent 以 dev dependency 形式发布的原因。对我做模板的工作来说，这在 Cloudflare Workers 上尤其关键：运行时 bundle 是从 node_modules 组装出来的，各种约定则来自 Workers TypeScript docs。

安装与首次运行

CLI 通过 npx 运行，不需要全局安装任何东西。它必须在项目内运行，因为它是从当前目录解析工作区的。

# 在项目根目录运行发现命令
npx @tanstack/intent@latest list

输出里的每一行都是一个已安装、且至少发布了一个技能的包，带版本号和技能数量。以下是 2026-10-22 在这里的实际输出：

读懂这份输出

有三件事很显眼。发现走的是普通的 npm 解析流程，所以发布过技能的包不需要任何额外配置就能被找到。技能数量差异很大，这反映出每位维护者对 agent 指导的投入程度不一。版本号同样重要——一份描述旧 API 的技能，比没有技能更糟。

在项目之外运行同一条命令，会打印 No intent-enabled packages found.，并附带一条提示：未来版本将要求显式的 intent.skills 白名单。这条提示在你把技能发布给陌生用户时尤其重要。

在这里多次运行 intent list，跨越 5 个月的使用期，发现到的集合始终没变。即使 CLI 版本不断推进，发现机制本身是稳定的。

按我的使用顺序，拆解全部命令

这个 CLI 暴露了十五个命令：list、exclude、load、meta、repair、validate、install、hooks、maintainer、review、stale、edit-package-json、setup、setup-github-actions 和 help。我每周用其中六个。

load —— 把单个技能拉进上下文

load 是 agent 真正会调用的命令。语法是 package#skill，输出是带 frontmatter 的原始 SKILL.md：

# 把 dotenv 技能加载进当前 agent 上下文
npx @tanstack/intent@latest load dotenv#dotenv

技能文本带着自己的 frontmatter 一起进来，所以 agent 能看到 name、description、license 和 source 元数据。这是一次文件读取，不是摘要，所以 agent 会逐字照做。

meta —— 面向作者的元技能

intent meta 会列出四个给库维护者用的元技能：domain-discovery、generate-skill、skill-staleness-check 和 tree-generator。它们是给 agent 看的指令，用来帮你写技能——这样你就不用逼着模型凭空编出一套 API 了。

maintainer —— setup、add、remove、status、sync、review、check

这是给"自己发布技能"的包用的命令。先把规划记录搭好，为一个新领域添加技能，然后同步技能树，再在 CI 里检查。

# 初始化规划记录，注册已有技能，安装 CI
npx @tanstack/intent@latest maintainer setup

# 为一个领域创建技能骨架
npx @tanstack/intent@latest maintainer add my-skill --domain my-domain --description "What it does"

# 让技能树与 SKILL.md frontmatter 对齐
npx @tanstack/intent@latest maintainer sync

setup 会写四样东西：skill_tree.yaml、domain_map.yaml、skill_spec.md，以及在不存在时创建 .github/workflows/check-skills.yml。它还会把 skills/ 下所有没登记过的 SKILL.md 补录进去。check 是 CI 闸门，遇到撰写问题、生成文件过期或存在待审项时都会让构建失败。

validate、stale、review —— 让技能保持诚实

这三个命令是"技能"和"过期的 README"之间的分界线。validate 检查 frontmatter，可以用 --fix 自动改掉能修的问题，也可以用 --check 直接让构建失败。它还接受 --set-version <version>，给命中的技能盖上 metadata.library_version 的章。

stale 汇报那些源码已经往前走的技能，--json 输出机器可读结果，--github-review 则写出用于评审的 PR 文件。review 拿一方技能和 Git 变更做对比，用 --base <ref> 指定基线。

从你自己的包里发布技能

如果你在维护一个包，这部分才是关键。技能是打进 npm tarball 一起发布的，所以 package.json 里的 files 数组必须包含 skills 目录：

{
  "name": "@tanstack/react-start",
  "version": "1.168.18",
  "files": ["dist", "src", "skills", "bin", "!skills/_artifacts"]
}

这是 2026-10-22 已发布的 @tanstack/react-start 包里真实的 files 数组。skills 这一项正是让技能对 intent list 可见的原因。

SKILL.md 的约定

那个包里的框架级技能，frontmatter 比简单技能要多。我在随包发布的 SKILL.md 里核对过的字段有 name、description、type、library、library_version、framework、requires 和 sources。requires 和 sources 让维护者既能表达技能之间的依赖，也能指向该技能所描述的源码。CLI 会把每个技能标记为 core、framework 或 sub-skill。

Vite 插件的顺序陷阱

@tanstack/devtools-vite 技能里写明：它的插件必须是 Vite 配置里的第一个插件，只支持 Vite 6 和 Vite 7，并且提供一个 inspect 热键、console 管道分级、带可配置端口和 host 的服务端事件总线，以及通过 launch-editor 接入编辑器集成的钩子。这些细节全都在技能里，没有一条在我对插件的记忆里。

过程中出过什么问题

这里没有一句是对工具的抱怨。它只是按顺序列出了那些让我没法在一天之内把技能发出去的东西。

npm 最新版与我 lockfile 之间的版本差

之前： 我的 package.json 把 @tanstack/intent 固定在 ^0.0.41，是 2026-05-16 在 commit id 572fb7d 里加的，而 npm 上的 latest 已经到了 0.5.6。

之后： 查看时我用 npx @tanstack/intent@latest 跑 CLI，需要写脚本的场景仍用固定版本。这个取舍是刻意的：在包本体还停在旧版本时却把开发工具钉死，混淆就是这么来的。

验证： 2026-10-22 我把 npm view @tanstack/intent version 和实际安装版本做了对比，并通读了 0.5.6 版本上述每条命令的 help 输出。

白名单提示

之前： 我以为 intent list 是一份稳定的契约，可以直接在上面搭东西。

之后： CLI 告诉我未来版本会要求显式的 intent.skills 白名单。当天那个会话我就把白名单条目加进了 package.json，这个工具也从"我在试的东西"变成了"我依赖的东西"。

什么时候该用 Intent，什么时候不该

Intent 是给"发布了包、而 agent 装上之后需要正确使用它"的维护者准备的。如果你写的是应用而不是库，经济账就变了：一个仓库，根目录一份 CLAUDE.md，没有版本偏差要防。

我自己的判断规则是：当你的包有不止一种使用形态时发布技能，当 API 在版本之间有破坏性变更时发布技能，或者当你的指导依赖那些开发者本会跳过的配置步骤时发布技能。

发布前的检查清单

• 确认 skills 出现在 package.json 的 files 数组里。
• 在 CI 里跑 intent validate --check，有错误就让构建失败。
• 跑 intent maintainer check --base <ref>，让过期的生成文件挡住合并。
• 发布时用 --set-version 盖上 metadata.library_version。
• 验证发布出去的 tarball 里确实包含 skills 目录，而不只是本地工作树。

最后一条是最多人跳过的。技能只存在于你的工作副本、却没进发布的 tarball，那么所有安装这个包的 agent 都看不到它。我检查的是 tarball，不是工作树。

这份指南的局限

这里的一切都是 2026-10-22 在这个仓库、这台机器上测出来的，数据来自 npm registry 近 30 天的生产数据。我没在 Windows 上测试过，也没有在共享 CI 矩阵里跑过 intent install 或 intent hooks，所以这两条命令请当作"文档里有说明"而不是"我验证过"。我也没做过"有技能 vs 无技能"的 agent 成功率基准测试，所以我没法告诉你那 41 个技能到底能带来多大提升。

披露一下：我开发并销售 TanStack Ship，也就是下面链接指向的产品，所以我与那个链接之间存在实质利益关系。上面每一项测量都是我自己复现的一方 CLI 输出；npm 下载量数据来自 registry 生产环境。

常见问题

TanStack Intent 能替代我的 README 吗？

不能，也不应该。README 讲的是这个包对正在浏览器里读它的人意味着什么。技能讲的是这个包怎么被正确使用，对象是一个已经决定要用这个包的 agent。我的包两者都保留，技能专注于那些跨版本会出问题的细节。

技能必须发布到 npm 才生效吗？

就发现这条路径而言，是的，因为发现流程读的是 node_modules 里已安装的包。开发期间我会直接从工作树里的路径加载技能。把技能发布到一个 agent 永远不会安装的地方是没有用的，因为没有任何东西会触发这次查找。

哪些 agent 支持 Intent？

技能格式就是带 frontmatter 的纯 markdown，而 intent install 和 intent hooks 会把加载指引写进受支持 agent 的配置里，包括 Copilot、Claude 和 Codex。这是一套约定而非私有 API，所以任何能读 SKILL.md 的 agent 都能在没有 CLI 的情况下使用它。

@tanstack/intent 稳定到可以依赖了吗？

2026 年内请把它当成一个移动靶。2026-10-22 时 CLI 告诉我 latest 是 0.5.6，它也警告说未来版本会要求显式白名单，而我自己仓库里还钉着旧版本。如果你要对它写脚本，就钉住版本；在任何会改动命令的版本发布前，重读一遍 help 输出。

skill 和 hook 有什么区别？

skill 是 agent 在判断这份指导与自己相关时才去读的指导内容。hook 是 CLI 安装进 agent 配置里的一种机制，用来把这份指导暴露出来或强制加载。skill 回答"要知道什么"，hook 回答"什么时候把它亮出来"。你可以只用 skill，不用 hook。

延伸阅读： Tanstack Intent Production Guide 2026 · Tanstack Query V5 Migration Complete Guide 2026 · Tanstack Hotkeys Complete Guide 2026

结论

TanStack Intent 是个小工具，但承诺很具体：如果你的 npm 包发布了技能，安装这个包的 agent 就能找到并加载它们，不需要人工去复制粘贴说明。CLI 给你发现、校验、过期检查和 CI 接线，格式也就是带 frontmatter 的 markdown，不是什么玄乎的东西。缺口都很窄，而且都点名了：已发布 CLI 和我钉住的依赖之间的版本差、一个大概率会变成强制项的白名单，以及一些我读过但没在真实负载下跑过的 flag。 如果你维护的是一个库，并希望 agent 能正确使用它，下一步成本很低：把 skills 目录加进 files 数组，跑一次 intent validate --check，然后发布。TanStack Ship 模板已经把技能接进了构建和 CI，SaaS boilerplate 对比则列出了哪些脚手架自带 agent-ready 配置。

本站的这篇文章会带上 canonical URL 和 BlogPosting JSON-LD，因此这些元数据会一路带进搜索结果和 AI 回答里。

延伸阅读

• TanStack Intent 文档
• GitHub 上的 TanStack Intent 源码
• npm 上的 @tanstack/intent
• Agent Skills 规范