本文由 Huifer 撰写，TangStack Ship 的独立开发者与维护者。我在 2026 年 Q1 首个发布周开始使用 TanStack Intent，并为每个 TanStack Ship 模块编写了 skill。在我的个人维护日志中，这项操作每周节省了大约三小时的重复上下文设置工作，用于处理样板文件的变更。这是我个人工作流的测量结果，而非受控基准测试，但改善幅度足够大，使得包分发的 skills 成为我维护该平台的核心方式。
已核实来源：TanStack Ship GitHub · TanStack Intent 仓库 · Agent Skills 规范 · TanStack Start 文档 更新日期：2026-07-20 · 更新日志
TL;DR： TanStack Intent 是一个 CLI 和打包规范，用于随 npm 包一起分发小型、任务专用的 Agent Skills。维护者编写并验证
SKILL.md文件，将skills目录纳入包中，并将 skills 与源码文档关联。消费者安装 Intent 指导，通过list从本地已安装的包中发现 skills，再通过load加载相关的一个。Skills 随依赖更新一起分发，但 Agent 仍需显式发现和加载；Intent 是分发与维护基础设施，而非魔法的模型记忆。
TanStack Intent 一段话概括
TanStack Intent 让库维护者可以将可组合的知识与代码一起分发。类型可以告诉 Agent 函数调用是否合法，文档可以向人类解释概念，但两者都无法可靠地告诉编程 Agent 在特定任务中应选择哪种模式。Skill 以精简的描述、当前规范、示例和反模式填补这一空白。
包管理器成为分发渠道。当应用程序安装了一个启用 Intent 的依赖时，该依赖发布的 skills 目录会随精确的包版本一起到达。Intent 可以在本地发现这些 skills，编程 Agent 只需加载当前变更相关的那个。升级包即通过同一依赖工作流升级知识产物。
官方项目将目标描述为"随 npm 包一起分发面向 AI 编程 Agent 的可组合知识"。截至 2026-07-20，我实际查看了 npm 而非仅凭记忆：@tanstack/intent 版本为 0.3.6，其仓库指向 github.com/TanStack/intent。读者可以重新运行下方的命令，因为版本会继续更新。
为什么文档和类型仍然存在缺口
训练数据混入了新旧 API。人类文档通常从概念讲起，而 Agent 需要的是紧凑的答案——"当此任务出现时，遵循这些文件、导入方式和约束"。TypeScript 可以拒绝错误的参数，但无法说明认证路由属于哪个特定布局、变更必须使类型化 key 工厂失效，或者 webhook 需要在业务逻辑之前具备幂等性。
CLAUDE.md 等项目级文件有所帮助，但将框架说明复制到每个仓库会造成漂移。半年后，应用程序可能已使用新版本包，而复制的说明仍在教旧 API。社区规则文件又引入了另一个责任归属不清的问题。
Intent 并非取代文档或类型。它从维护者掌控的来源派生出聚焦的 Agent 产物，并赋予该产物版本化的分发路径。最优组合仍是：人类阅读的文档、保证正确性的类型与测试，以及辅助任务选择的 skills。
Skills 应当精简并由意图触发
一个有用的 skill 不是总结整个框架。它只回答一类请求：配置插件、添加受保护的路由、管理搜索参数，或迁移 API。其描述至关重要，因为那是 Agent 在 skill 检查期间使用的紧凑信号。
在本仓库中，运行 intent list 发现了 11 个本地启用 Intent 的包中共 41 个 skills，按 core、framework、lifecycle 和子 skill 关注点分组。这比将 41 份完整文档注入每次提示要实用得多。
Agent Skill 的结构
Skill 最少由一个目录组成，其中包含具有 YAML frontmatter 和过程性 markdown 的 SKILL.md。开放的 Agent Skills 规范定义了可移植的形态；Intent 则在其周围添加了包发现、加载、验证和防过时工作流。
一个简化的账单 skill 可以如下所示：
---
name: billing-webhook-idempotency
description: Use when adding or changing a Stripe webhook that mutates billing state.
---
# Billing webhook idempotency
## Before editing
- Read `docs/billing/event-ledger.md`.
- Locate the existing event claim and audit helpers.
## Required invariants
1. Verify the signature against the untouched request body.
2. Claim `event.id` through the database unique constraint.
3. Attach `source_event_id` to money-like mutations.
4. Return a retryable response when processing fails.
## Verification
- Replay one signed event concurrently.
- Assert one business effect and one completed ledger entry.
描述说明何时加载该 skill。正文命名来源、不变式和验证流程。它不会浪费 token 重述 Stripe 的整个 API。真实的 skills 可能包含相邻的示例或文档文件，但入口点保持精简。
来源链接使过时可被检测
Skill 是派生知识，因此漂移是其核心风险。Intent 的 stale 工作流会标记：源码文档已变更的 skills、已漂移的生成产物，以及缺少预期覆盖的公共 workspace 包。setup 命令可以安装 CI 模板，使漂移出现在常规审查期间而非 Agent 生成过时代码之后。
这正是相比粘贴式提示词的关键改进。版本化本身只是分发变更；来源追踪和 CI 让维护者在知识变更时有动力去审查 skill。
Agent 如何消费已安装包中的 skills
常见的简略说法——"Claude Code 或 Cursor 自动从 node_modules 读取 skills"——过于绝对。Intent 记录的消费者流程是显式的。运行 install 将 skill 加载指导写入支持的 Agent 配置文件。工作期间，Agent 通过 list 检查本地可用 skills，选择匹配的包和 skill 引用，再通过 load 加载其 SKILL.md。
# Add discovery/loading guidance to the project's agent configuration
npx @tanstack/intent@latest install
# See skills shipped by installed packages
npx @tanstack/intent@latest list
# Load only the guidance relevant to the task
npx @tanstack/intent@latest load \
@tanstack/router-core#router-core/auth-and-guards
命令运行器可以互换：npm 用 npx、pnpm 用 pnpm dlx、Bun 用 bunx。当前 README 还记录了 Yarn Plug'n'Play 支持，以及通过 npm 互操作对 Deno 的尽力支持。请查阅官方兼容性表，而非假设每个编辑器以相同方式解析包。
不同的编程 Agent 有不同的原生约定和钩子系统。Intent 不承诺每个工具都会静默索引每个依赖。它安装的是可移植的行为：检查、选择、加载，然后工作。这保持上下文精简，并使选定的来源在 Agent 转录中可见。
list 在这里实际发现了什么
撰写本文时，我从 workspace 根目录运行了项目所需的 skill 检查。它在 TanStack Start、Router、Devtools、Redux Toolkit、dotenv 及相关包中发现了本地 skills。每条结果都包含包名、已安装版本、skill 名称、描述和来源。
该结果仅在此 lockfile 快照下可复现。另一个项目将看到不同的集合，而没有发布 skills 的包不会仅仅因为安装了 Intent 就出现。这种限制是健康的：CLI 报告的是实际的本地产物，而非假装模型知道每个依赖。
第一个实用示例：Router 代码生成
路由是包自有知识最快产生价值的地方。模型见过 React Router、多个 TanStack Router 版本以及框架特定的约定式文件路由。一个看似合理的响应可能导入错误的包、使用过时的文件名，或在仍具说服力的外表下丢失类型化的路由上下文。
已安装的 Router skills 将领域划分为：路由树基础、守卫、代码分割、加载、导航、错误处理、路径参数、搜索参数、SSR 和类型安全。如果任务是"添加一个认证布局"，Agent 可以加载守卫指导而非整本路由手册。如果任务涉及修改已验证的搜索参数，它加载的是另一个子 skill。
这不能保证输出正确。它只是改善了决策点可用的证据。编译、测试和审查仍然是必选项。我将 skill 视为维护的运行手册，而非可以绕过验证的权威来源。
为什么这比手写 CLAUDE.md 更好
项目文件仍拥有应用特定的决策：目录边界、产品术语、测试命令、隐私约束和架构决策。包 skill 则拥有库特有的知识。保持这些职责分离减少了重复。
包 skill 随依赖更新、可检查源码是否过时，并对所有消费者共享。项目文件保持精简，只解释使应用与众不同的部分。当指令冲突时，应用的显式约束应获胜，且 Agent 应暴露冲突而非悄然合并两者。
结果是组合：框架指导 + 包指导 + 项目指导，在需要时加载。这比一个巨大的规则文件更易维护，比寄望于模型训练包含正确发布内容更透明。
为 TanStack Ship 模块打包 Skills
TanStack Ship 有 14 个生产模块，涵盖计费、认证、用户、内容、存储、活动、积分、邮件、邀请、UTM 捕获、归因、节假日、短链接和收入运营。我在打包任务级 skills 时聚焦于危险的接缝处，而非为每个模块写一份营销总结。
计费指导涵盖原始请求体验证、事件身份、审计记录和队列。UTM 指导在 SSR、cookie、注册和结账过程中保留归因。管理路由指导涵盖授权、导航注册、加载器和错误状态。博客指导涵盖 frontmatter、i18n 和发布检查。平台功能展示了产品领域；skills 则编码了 Agent 如何安全地修改它们。
付费模块的完整 skill 内容不一定公开，因此 GitHub 组织验证的是维护者身份和公开足迹，而非关于私有包文件的每一项声明。这是商业源码分发的局限，也是我不将私有 skill 计数作为独立基准呈现的原因。
三小时/周 claim 的测量方式
我的估算是通过维护笔记比较首次模块 skills 前后的重复提示得出的。我计算了纠正已知规范错误和重新说明模块上下文所花的时间。未对任务进行随机化、未对审查者设盲、也未保持模型版本一致。新业务逻辑的收益远低于重复的框架和模块工作。
诚实的结论是个人层面的：skills 在我的工作流中每周节省了约三小时的上下文修复工作。通用结论应由各团队自行测试。在声称百分比改进之前，跟踪重复任务的首轮测试成功率、纠正轮次和 diff 接受时间。
维护者工作流：上线、验证、保持最新
Intent 暴露了分离的消费者和维护者工作流。消费者安装指导、列清单和加载。维护者搭建 skill 树、审查生成的知识、验证文件、检查过时，并将 skills 目录纳入 npm 包中。
# Explore the guided maintainer workflow
npx @tanstack/intent@latest scaffold
# Validate one package's skills from a monorepo root
npx @tanstack/intent@latest validate packages/billing/skills
# Check all workspace skills against their declared sources
npx @tanstack/intent@latest stale
# Copy Intent's CI workflow templates into .github/workflows
npx @tanstack/intent@latest setup
维护者还应在发布前检查打包的 tarball。一个完美的本地 skill 如果被遗漏在 npm files 之外，也无法帮助消费者。测试应验证公共包包含 skills/**，同时在适当情况下排除内部生成产物。
局限与失效模式
Skill 可能模糊、错误或过时。Agent 可能跳过 skill 检查、选择一个宽泛的 skill，或者加载了正确指导但仍写出有问题的代码。工具兼容性也参差不齐，上下文优先级可能存在差异。Intent 改善了知识分发；它无法标准化每个 Agent 运行时。
不含测试的 skills 可能产生虚假自信。每个技术 skill 都应以验证命令结尾，并说明其无法验证的边界。安全敏感的工作流即使生成的代码通过测试也需要人工审查。
还有维护成本。框架作者必须在 API 和源码文档变更时审查 skills。Intent 的验证和过时检查使该成本可见，但无法消除。不愿拥有派生指导的团队应将 skill 表面积保持在小规模。
从不轻易承诺开始
在安装任何其他内容之前，先在现有 workspace 中运行 npx @tanstack/intent@latest list。如果出现相关的本地 skills，加载一个并将产生的变更与正常工作流进行比较。如果希望在工作流的 Agent 配置中获得持久指导，再运行 install。
库维护者应从一个易出错的 capability 开始，将其附加到权威的源码文档，添加具体的验证部分，进行验证，并检查包 tarball。只有在观察到 Agent 正确选择并使用它之后才扩展。
有关更多 AI 辅助开发上下文，请浏览博客和对比指南。在重复的真实工作上评估该方法，而非在一个精心打磨的单次演示上评估。
TanStack Intent 的有用理念很朴素：离 API 最近的维护者应该拥有该 API 如何被 Agent 使用的一份精简的、版本化的说明，而该说明应该通过与代码相同的包渠道分发。
从功能概览开始，尝试 TanStack Ship 预绑定的 Agent Skills，选择与你所需模块匹配的包；在工作流在你自己的 Agent 中验证有效之后，再查阅定价。