1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里反复出现的 Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills 这些词基本可以确定这里说的 skills是围绕 AI Agent智能体构建的一套可插拔能力模块体系。简单讲就是把一个智能体原本“什么都能聊但什么都做不深”的状态拆解成一个个独立、可复用、可组合的技能包让它在特定任务上表现得像一个受过专门训练的专家。这件事解决的核心痛点很直接。过去我们做一个 AI 应用往往是把所有提示词、工具调用、业务逻辑塞进一个巨大的系统提示里结果就是提示词越写越长、维护越来越难、换个场景就得重写一遍。skills 的思路是把“能力”从“主体”里剥离出来——主体负责理解意图和调度skills 负责具体执行。这跟微服务架构的思路几乎一模一样只不过服务对象从后端系统变成了 AI Agent。适合看这篇内容的人有三类。第一类是正在做 AI 应用开发的前端或全栈工程师想给自己的产品加上更专业的垂直能力第二类是已经在用 Claude、Codex 这类工具做自动化的人想搞清楚 skills 的安装、开发和调试逻辑第三类是对 Agent 架构感兴趣、想从第一性原理理解“能力模块化”这件事的技术爱好者。不管你之前有没有接触过 Agent 开发只要你会写一点代码、能看懂配置文件这篇内容都能让你把 skills 这件事从头到尾捋清楚。我下面会按照“整体设计思路 → 核心细节拆解 → 实操落地 → 问题排查”这条线来讲中间会穿插我自己踩过的坑和一些文档里不会写的经验。内容偏实操尽量少讲空话。2. 整体设计与思路拆解为什么要把能力拆成 skills2.1 从单体提示词到模块化能力的演进逻辑早期做 AI 应用最典型的做法就是写一个超长的 system prompt把角色设定、输出格式、工具说明、业务规则全部塞进去。我最早做的一个客服机器人就是这么干的提示词写到三千多字结果模型开始“选择性遗忘”——前面写的规则后面就不遵守了。这不是模型笨而是上下文里信息密度太高注意力被稀释了。skills 的出现本质上是对这个问题的工程化回应。它的核心假设是一个 Agent 不应该在同一个上下文里同时处理所有事情而应该根据任务类型动态加载对应的能力模块。这就像一家公司不会让一个员工同时干财务、法务、市场和客服而是分成不同部门需要哪个部门就调用哪个部门。从架构上看skills 通常包含几个要素一个描述文件说明这个 skill 叫什么、干什么、什么时候用、一段核心逻辑可能是提示词模板也可能是可执行代码、以及可选的工具依赖比如需要调用某个 API 或读取某个文件。Agent 在运行时根据用户意图匹配到对应的 skill然后把 skill 的内容注入上下文任务完成后释放。这个“按需加载”的机制是 skills 相比单体提示词最大的优势。2.2 skills 与 Agent、工具调用之间的边界这里有个容易混淆的点skills 和 tool calling工具调用到底什么关系我的理解是工具调用是“手”skills 是“操作手册”。工具调用解决的是“能不能做”的问题比如能不能发 HTTP 请求、能不能读文件skills 解决的是“怎么做才对”的问题比如发请求时参数怎么填、读文件后怎么解析、遇到异常怎么处理。举个例子。你要做一个自动整理会议纪要的 Agent。工具调用层面你需要文件读取工具和文本写入工具但 skills 层面你需要一个“会议纪要生成”技能里面定义了输入是录音转写文本输出是结构化纪要中间要提取待办事项、要标注发言人、要按议题分段。这些规则不是工具能提供的必须由 skill 来承载。再往上一层是 Agent 本身。Agent 负责理解用户说“帮我整理一下今天的会议记录”这句话然后判断该调用哪个 skill再把 skill 的输出组织成自然语言回复。所以三者的关系是Agent 做调度skills 做专业处理工具做底层执行。搞清楚这个分层后面开发和调试的时候就不会把问题归错地方。2.3 为什么 Google Cloud、GKE、Genkit 会出现在这个话题里热搜词里出现 Google Cloud、GKE、Genkit说明 skills 这套东西不只是本地玩玩的脚本而是可以部署到云端的生产级方案。GKE 是 Google 的 Kubernetes 服务Genkit 是 Google 推出的 AI 应用开发框架。把它们和 skills 放在一起透露出的信息是skills 可以作为独立的服务部署在容器里通过 Genkit 这样的框架编排然后在 GKE 上做弹性伸缩。这个组合的价值在于当你的 Agent 需要服务大量用户时不可能把所有 skills 都塞在一个进程里。把每个 skill 做成独立的容器化服务按需扩缩容这才是工程上可持续的做法。当然对于个人开发者或者小规模场景本地跑一个轻量级的 skill 加载器就够了不一定非要上云。但了解这个上限在哪里对你做技术选型是有帮助的。3. 核心细节解析与实操要点skills 的组成与加载机制3.1 一个标准 skill 的目录结构与文件说明我参考了几个主流实现包括 Claude 的 agent skills 和 codex 的 skills 机制一个典型的 skill 目录大概长这样my-skill/ ├── skill.json # 技能描述文件定义名称、触发条件、输入输出 ├── prompt.md # 核心提示词模板 ├── handlers/ # 可选的代码处理逻辑 │ └── process.js └── resources/ # 可选的静态资源 └── template.txtskill.json是整个技能的入口里面最关键的是trigger字段它决定了 Agent 在什么情况下会加载这个 skill。trigger 可以是一个关键词列表也可以是一段自然语言描述让模型自己判断。我个人的经验是对于确定性高的场景用关键词匹配更稳对于开放性场景用语义匹配更灵活但后者需要更仔细地测试边界情况。prompt.md是技能的核心里面写的是这个 skill 被激活后注入到上下文里的内容。这里有个技巧不要把 prompt.md 写成一个完整的对话提示而是写成一个“任务说明书”。因为 Agent 本身已经有自己的系统提示了skill 的提示应该是补充性的专注于这个技能特有的规则和格式要求。3.2 触发机制Agent 如何知道该用哪个 skill这是整个体系里最容易被低估的部分。很多人以为只要把 skill 写好了Agent 自然就会用。实际上触发机制的设计直接决定了 skills 体系的可用性。常见的触发方式有三种。第一种是显式触发用户在输入里直接提到技能名称比如“用会议纪要技能帮我整理一下”。这种方式最可靠但用户体验不够自然。第二种是关键词触发skill.json 里配置一组关键词用户输入命中关键词就激活。这种方式实现简单但容易误触发比如你配了“总结”这个词结果用户说“总结一下今天天气”也会激活会议纪要技能。第三种是语义触发把 skill 的描述和用户输入一起交给模型判断让模型决定是否加载。这种方式最自然但需要模型有足够的判断力而且每次判断都会消耗 token。我实际用下来最稳的方案是“语义触发 关键词兜底”。平时靠语义判断但当用户明确说了技能名称时直接走关键词匹配跳过模型判断。这样既保证了自然交互又给了用户一个确定性的入口。3.3 上下文注入skill 加载后发生了什么当 Agent 决定加载某个 skill 后接下来发生的事情是skill 的 prompt.md 内容被拼接到当前对话的上下文里同时 skill 声明的工具依赖被注册到可用工具列表中。这个过程听起来简单但有几个细节需要注意。第一是注入位置。skill 内容应该注入在系统提示之后、用户消息之前这样模型会把它当作“当前可用的能力说明”而不是“用户说的话”。如果注入位置不对模型可能会把 skill 的说明当成用户指令来执行导致行为异常。第二是上下文长度控制。每个 skill 都会占用一定的上下文窗口如果同时加载多个 skill很容易把窗口撑满。我的做法是限制同时激活的 skill 数量一般不超过三个并且给每个 skill 的 prompt.md 设一个长度上限超过就拆分或者精简。第三是优先级处理。当多个 skill 同时被触发时需要一个优先级规则来决定谁先谁后。我通常按“具体性”排序越具体的 skill 优先级越高。比如“会议纪要”比“文本总结”更具体同时命中时优先用前者。3.4 工具依赖的声明与隔离skill 可以声明自己需要哪些工具。比如一个“网页内容提取”skill 可能需要 HTTP 请求工具和 HTML 解析工具。这里的关键是隔离skill A 声明的工具不应该被 skill B 随意使用否则会出现权限混乱和意外调用。实现隔离的方式通常是在加载 skill 时只把该 skill 声明的工具注册到当前上下文任务结束后注销。这要求 Agent 框架支持动态工具注册。如果你用的是 Genkit 这类框架它本身就有工具管理的机制可以直接利用。如果是自己手写的加载器就需要自己维护一个工具注册表按 skill 维度做作用域隔离。注意工具隔离没做好的话会出现一个 skill 调用了另一个 skill 的工具但参数格式不匹配的情况排查起来非常痛苦。建议在开发阶段就加上工具调用的日志记录是哪个 skill 触发了哪个工具。4. 实操过程与核心环节实现从零搭一个 skills 加载器4.1 环境准备与依赖安装我以 Node.js 环境为例因为 Genkit 对 Node 支持比较好而且前端开发者上手成本低。你需要准备的东西不多Node.js 18 以上版本一个包管理器npm 或 pnpm 都行一个模型 API 的访问凭证这个根据你用的模型服务来定可选的 Genkit CLI如果你想用它的开发服务器和调试工具安装 Genkit 的命令是npm install -g genkit-cli npm install genkit genkit-ai/googleai如果你不想用 Genkit也可以直接用一个轻量的 HTTP 客户端加自己写的加载逻辑核心原理是一样的。我下面会以“自己写加载器”为主线因为这样你能看清每个环节用框架的话很多细节被封装了反而不好理解。4.2 编写第一个 skill以“会议纪要生成”为例先建目录结构mkdir -p skills/meeting-notes/handlers touch skills/meeting-notes/skill.json touch skills/meeting-notes/prompt.mdskill.json的内容{ name: meeting-notes, description: 将会议录音转写文本整理成结构化会议纪要包含议题、结论、待办事项, triggers: [会议纪要, 会议记录, 整理会议], tools: [read_file, write_file], priority: 10, maxContextLength: 2000 }prompt.md的内容我写了一个精简版你正在执行会议纪要生成任务。输入是一段会议转写文本你需要输出结构化纪要。 输出格式要求 1. 会议主题一句话概括 2. 参会人员从文本中提取 3. 议题与结论按议题分段每个议题下列出讨论要点和最终结论 4. 待办事项格式为“负责人 - 事项 - 截止时间”没有明确截止时间的标注“待定” 注意事项 - 不要编造文本中没有的信息 - 如果某个议题没有明确结论标注“未达成结论” - 待办事项只提取明确指派了负责人的条目这个 prompt 的关键在于“输出格式要求”和“注意事项”两部分。格式要求让输出稳定可解析注意事项防止模型自由发挥。我试过不写注意事项的版本结果模型经常自己脑补一些会上没说的内容这在正式场景里是致命的。4.3 加载器的核心逻辑实现加载器要做的事情按顺序是扫描 skills 目录、读取每个 skill.json、根据用户输入匹配 skill、加载匹配到的 skill 的 prompt 和工具、注入上下文、调用模型、返回结果。匹配逻辑我用了一个简单的打分机制function matchSkills(userInput, skills) { const input userInput.toLowerCase(); const scored skills.map(skill { let score 0; // 关键词匹配 for (const trigger of skill.triggers) { if (input.includes(trigger.toLowerCase())) { score 10; } } // 描述语义匹配简化版实际可以用向量相似度 const descWords skill.description.toLowerCase().split(); for (const word of descWords) { if (word.length 1 input.includes(word)) { score 1; } } return { skill, score }; }); return scored .filter(item item.score 0) .sort((a, b) b.score - a.score || b.skill.priority - a.skill.priority) .slice(0, 3) // 最多同时激活3个 .map(item item.skill); }这个打分机制很粗糙但实际用下来对于关键词明确的场景已经够用了。如果你要做语义匹配可以把 skill 的 description 预先算成向量存起来运行时算余弦相似度。不过那套东西复杂度高不少建议先把关键词匹配跑通再考虑升级。4.4 上下文组装与模型调用匹配到 skill 后组装最终发给模型的 messagesfunction buildMessages(userInput, matchedSkills) { const systemPrompt 你是一个智能助手根据当前加载的技能来完成任务。; const skillContext matchedSkills.map(skill { const prompt fs.readFileSync( path.join(skill.dir, prompt.md), utf-8 ); return 【当前技能${skill.name}】\n${prompt}; }).join(\n\n); return [ { role: system, content: systemPrompt }, { role: system, content: skillContext }, { role: user, content: userInput } ]; }这里我把 skill 内容放在第二条 system 消息里而不是拼在第一条里。这样做的好处是当没有匹配到任何 skill 时skillContext 为空消息结构保持一致不会因为消息数量变化导致模型行为波动。调用模型的部分就按你用的 SDK 来写没什么特别的。我用的是流式输出因为会议纪要这种长文本流式能让用户更快看到结果。4.5 部署到 GKE 的简化流程如果你要把这套东西部署到 GKE大致流程是把加载器打包成 Docker 镜像、推送到镜像仓库、写一个 Deployment 和 Service 的 YAML、用 kubectl 应用。核心的 Dockerfile 大概这样FROM node:18-slim WORKDIR /app COPY package*.json ./ RUN npm install --production COPY . . EXPOSE 3000 CMD [node, server.js]Deployment 的副本数我建议先设 2因为 AI 请求的响应时间波动大单副本容易在并发时排队。资源限制方面每个副本给 512Mi 内存和 500m CPU 起步根据实际负载再调。GKE 的自动扩缩容可以根据 CPU 使用率来配但要注意模型调用的瓶颈通常在网络等待而不是 CPU所以纯 CPU 指标可能不够灵敏有条件的话用自定义指标比如请求队列长度。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么办这是最高频的问题。不触发的原因通常有三个关键词没覆盖到、语义匹配阈值太高、或者 skill.json 格式有误导致加载失败。排查顺序建议从下往上先确认 skill 是否被正确加载打印加载列表再确认匹配分数打印打分结果最后才怀疑模型判断。误触发相对更难处理因为往往是关键词太宽泛。我的经验是trigger 关键词尽量用“组合词”而不是“单词”。比如“总结”这个词太泛改成“会议总结”或“文档总结”就精准很多。另外可以加一个否定关键词列表命中否定词时直接跳过该 skill。5.2 多个 skill 冲突时的处理策略当两个 skill 同时被高分匹配时如果它们的输出格式要求互相矛盾模型会陷入混乱。比如一个 skill 要求输出 JSON另一个要求输出 Markdown同时加载就会出问题。我的处理策略是在 skill.json 里加一个exclusiveGroup字段同一组的 skill 只能激活一个。加载器在匹配后做一次去重同组只保留分数最高的。这个机制简单但有效能避免大部分冲突。5.3 上下文超长导致的性能下降skill 加载多了上下文变长模型响应变慢、成本变高、还容易“忘记”前面的内容。除了限制同时激活数量还可以做 skill 内容的懒加载先只注入 skill 的名称和一句话描述等模型明确表示要用某个 skill 时再注入完整内容。这需要两轮模型调用但总体成本可能更低。5.4 常见问题速查表问题现象可能原因排查方法解决方向skill 完全不触发skill.json 格式错误检查 JSON 是否合法用 JSON 校验工具修复skill 偶尔触发关键词覆盖不全打印匹配分数日志补充 trigger 关键词输出格式不稳定prompt 约束不够强对比不同输入的输出增加格式示例和反例响应特别慢上下文过长统计注入的 token 数精简 prompt 或懒加载工具调用报错工具未注册或参数错检查工具注册日志确认 skill 声明的工具已加载多 skill 输出混乱格式要求冲突检查同时激活的 skill设置 exclusiveGroup5.5 几个文档里不会写的实操心得第一个心得skill 的 prompt.md 要当代码来维护用版本控制管理每次修改都记录改了什么、为什么改。我早期改 prompt 很随意结果出现问题时根本不知道是哪个版本引入的。第二个心得给每个 skill 写测试用例。准备一组输入和期望输出每次修改 prompt 后跑一遍。不需要很复杂五到十个用例就能覆盖大部分边界情况。这个习惯帮我省了无数次回归排查的时间。第三个心得skill 的命名要具体不要用“helper”“utils”这种模糊词。名字本身就是给模型看的信号叫“extract-action-items”比叫“text-process”能让模型更准确地判断使用场景。第四个心得开发阶段把每次 skill 匹配的结果和最终组装的完整 prompt 都打到日志里。出问题时第一时间就能看到模型到底收到了什么比盲目改 prompt 高效得多。6. skills 体系的扩展方向与个人体会这套东西跑通之后扩展方向其实很多。一个方向是 skill 的组合编排让多个 skill 按流水线方式串联前一个的输出作为后一个的输入。比如“录音转写 → 会议纪要 → 待办提取 → 日历写入”这样一条链。另一个方向是 skill 的自动生成用模型根据一段任务描述自动生成 skill.json 和 prompt.md 的初稿人工再微调。还有一个方向是 skill 的市场化把常用的 skill 打包分享别人可以直接安装使用这也是热搜词里“skills 下载平台”“skills 大全”这些词反映出的需求。我自己用下来最深的体会是skills 这套体系的价值不在于技术有多复杂而在于它强迫你把“能力”这件事想清楚。写单体提示词的时候你很容易把一堆规则混在一起反正能跑就行。但拆成 skill 的时候你必须回答这个能力的输入是什么、输出是什么、边界在哪里、什么时候该用什么时候不该用。这些问题想清楚了不管用什么技术实现效果都不会差。另外一点不要一上来就追求大而全的 skill 库。我一开始建了十几个 skill结果维护不过来很多根本没用上。后来砍到五个核心 skill每个都打磨到位整体效果反而更好。skill 的数量不是重点覆盖高频场景、每个都稳定可靠才是关键。