TanStack AI Skills Skill 技能

技能简介

@tanstack/ai-skills 是 TanStack AI 官方包，把可移植的 Agent Skills（SKILL.md）做成一等公民的 chat() 中间件。当前 v0.1.20，MIT 协议，所属 TanStack/ai 仓库在 GitHub 上约 3200 星、365 个 fork。核心思路是：withSkills 只把技能目录的简述渲染进系统提示，并给模型一个 load_skill 工具，模型自己挑中某个技能后才去拉完整说明，因此庞大的技能库不会给每一次请求都增加上下文负担。

核心能力

1. 目录加按需加载：目录进系统提示，完整指令只在 load_skill 被调用时进入上下文；同一对话中重复加载同一技能会返回简短的「已加载」标记，而不是重复正文。
2. 零 Provider 沙箱依赖：这条可移植路径跑在任何支持工具调用的模型上，不需要厂商沙箱（与 Provider Skills 是两条互不混用的路径）。
3. 目录预算控制：maxCatalogTokens 默认 4000，超出即抛错，除非自行提供 reducer 压缩目录，保证模型看到的目录始终可信。
4. 人工确认开关：requireApproval 默认为 false，设为 true 后 load_skill 执行前需要人工批准。
5. 按模型家族渲染：Anthropic 模型拿到它训练过的 available_skills XML，其余模型使用普通 markdown 列表，可用 renderCatalog 或 instructionTemplate 覆盖。
6. 多种技能来源：内联技能、目录扫描、构建时打包、自建存储与 S3 各自独立入口，可组合使用。
7. 技能源契约与一致性测试：提供 SkillSource 契约与一致性测试套件，检查生产环境真正会出问题的点——缺失技能应抛错而不是返回空、拒绝越界路径、相同内容 revision() 稳定、并发 list() 结果一致。

安装配置

1. 安装依赖：npm install @tanstack/ai-skills（pnpm、yarn 用法相同）。
2. 定义技能：用 inlineSkill({ name, description, instructions }) 声明，name 需唯一，description 用于目录展示，instructions 是完整正文。
3. 接入中间件：在 chat() 的 middleware 数组中传入 withSkills(...)；传入数组时按名称排序并自动去重。
4. 调优目录：withSkills(sources, { maxCatalogTokens: 4000, requireApproval: true })，超出预算时用 reducer 处理。
5. 接入具体模型：官方示例使用 anthropicText('claude-sonnet-4-5') 作为 adapter，返回流式响应使用 toServerSentEventsResponse(stream)。

使用步骤

1. 安装包并创建技能定义，先用内联技能起步，后续再迁移到目录或远程来源。
2. 把 withSkills(skill) 放入 chat() 的 middleware 数组。
3. 发起一次对话，模型在系统提示中看到技能目录。
4. 模型判断需要某个技能时调用 load_skill，正文此时才被载入上下文。
5. 按需调参：技能数量多时压缩目录，涉及高风险操作时打开 requireApproval。
6. 自建技能源时按 SkillSource 契约实现，并跑一遍一致性测试套件后再上线。

适用场景

1. 给自己的应用接入一批可移植技能，同时不想为每个模型厂商单独适配。
2. 技能库规模大（几十上百个），需要控制每次请求的上下文成本。
3. 希望技能随应用一起版本化、随构建一起分发。
4. 需要在 load_skill 前插入人工审批的高风险工作流。
5. 团队自建技能存储（如 S3 或内部服务）并希望有统一契约与测试保障。

适用人群

使用 TanStack AI 或 TypeScript 构建 LLM 应用的开发者；要设计自有 Agent Skills 体系的团队；关注上下文成本与可控性的 AI 应用架构师；正在做 Agent 工具调用的工程师。

工作原理

withSkills 作为中间件拦截每次 chat() 调用，把所有来源的技能压缩成目录，按模型家族选择 XML 或 markdown 渲染后注入系统提示，并在工具列表中注册 load_skill。模型调用 load_skill 时，中间件从对应来源按需读取技能正文与随附文件并注入对话，重复请求走短路返回已加载标记。目录体积由 maxCatalogTokens 与 reducer 共同约束，超限直接报错而不是静默截断。

官方链接

• npm：https://www.npmjs.com/package/@tanstack/ai-skills
• 文档：https://tanstack.com/ai/latest/docs/skills/agent-skills
• GitHub：https://github.com/TanStack/ai