1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份职场软技能合集。但结合热搜词里反复出现的 Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills 这些词方向其实很明确——这里说的 skills是围绕 AI Agent 构建的一套可复用能力模块也就是让智能体具备“会做某件事”的封装单元。我把它理解成一句话skills 是 Agent 的“技能包”把提示词、工具调用、执行逻辑、上下文约束打包成一个可插拔的单元让 Agent 在特定场景下稳定完成特定任务。它解决的核心问题是通用大模型什么都能聊但落到具体业务里经常“会说不会做”而 skills 就是把“会做”这件事工程化。这篇文章适合三类人看。第一类是正在做 AI Agent 应用的前端或全栈开发者想搞清楚 skills 的工程结构第二类是已经在用 Google Cloud、GKE、Genkit 这套技术栈想把 Agent 能力接进现有系统的团队第三类是对 Agent Skills 感兴趣、看过一些概念但没动手跑通过一个完整 skill 的爱好者。我会从设计思路、核心结构、实操落地、问题排查几个角度把这件事讲透尽量让你看完能自己写一个能跑的 skill。需要先说明一点skills 目前没有唯一标准不同平台、不同框架对它的定义有差异。Anthropic 系的 Agent Skills 偏向文件系统里的技能目录加说明文档OpenAI 系的 codex skills 偏向可调用工具集Google 的 Genkit 则把它做成 flow 和 tool 的组合。所以下面讲的内容我会以“通用工程实践”为主线具体到某个平台时再单独说明避免你被单一实现绑死。2. 整体设计思路为什么要把能力拆成 skills2.1 从“一个大提示词”到“一堆小技能”的转变早期做 Agent最常见的做法是写一个超长 system prompt把角色、规则、工具说明、输出格式全塞进去。我试过刚开始很爽改起来很痛苦。一个 3000 字的提示词改一行可能影响三个功能测试成本极高。更麻烦的是当 Agent 要同时处理“查天气”“写周报”“调接口”三件事时提示词里会互相干扰模型经常把 A 场景的规则套到 B 场景上。skills 的思路正好相反把能力按场景切开每个 skill 只负责一件事有自己的触发条件、执行步骤和输出约束。主 Agent 只做路由和编排具体干活交给 skill。这样做的好处很直接——改一个 skill 不会影响其他 skill测试可以单独测复用也方便同一个“发送邮件”skill 可以被周报 Agent、客服 Agent、运维 Agent 同时调用。这个转变背后其实是一个工程常识关注点分离。前端组件化、后端微服务化都是同一个逻辑。Agent 能力也一样当它复杂到一定程度就必须拆。2.2 skills 和普通 tool calling 的区别在哪有人会问这不就是 function calling 吗我直接注册几个工具不就行了。区别在于粒度和管理方式。普通 tool calling 通常是一个函数对应一个动作比如get_weather(city)。而一个 skill 往往包含多个步骤、多个工具调用甚至包含条件分支和中间状态。举个例子“生成周报”这个 skill内部可能要先调query_database拿数据再调summarize做摘要再调format_markdown排版最后调send_email发送。对外它只暴露一个入口对内它自己编排。另一个区别是上下文管理。skill 可以自带说明文档、示例、约束条件Agent 在调用前能读到“这个技能怎么用、什么时候用、注意什么”。tool calling 一般只有函数签名和简短描述复杂场景下模型容易用错。2.3 选型时要想清楚的三个问题在动手写之前我建议先回答三个问题这决定了你的 skill 架构怎么搭。第一skill 的触发方式是什么。是用户显式指定还是 Agent 根据意图自动路由前者简单可控后者灵活但需要更精细的描述和测试。我一般建议核心流程用显式触发边缘场景用自动路由。第二skill 之间要不要共享状态。如果多个 skill 需要读写同一份数据就要设计一个共享的 context 或 memory 层。如果各自独立那就简单很多。我踩过的坑是一开始没设计共享层后来两个 skill 都要用用户信息只能各自查一遍浪费调用还容易不一致。第三skill 的边界怎么划。太细会导致 skill 数量爆炸编排复杂太粗又失去拆分的意义。我的经验是一个 skill 对应一个“用户可感知的完整任务”。比如“查天气”是完整任务“查天气并决定穿什么”也是完整任务但“调用天气 API”就不是那是 skill 内部的步骤。3. 核心结构解析一个 skill 到底由什么组成3.1 元信息层让 Agent 知道“我是谁、什么时候用我”元信息是 skill 的门面通常包括名称、描述、触发条件、输入输出格式。这部分看起来简单但写不好直接影响路由准确率。名称要短且唯一避免歧义。我见过有人把 skill 命名成process_data结果 Agent 根本不知道什么时候该用它。改成generate_weekly_report之后路由准确率明显提升。描述要写清楚三件事做什么、什么时候用、不做什么。最后一点很多人忽略但它很重要。比如“生成周报”skill 的描述里应该写明“仅用于周期性工作总结不用于实时数据查询”这样 Agent 在遇到实时查询需求时就不会误触发。触发条件可以用自然语言也可以用结构化规则。Genkit 里通常用 tool 的 description 加参数 schema 来表达Anthropic 的 Agent Skills 则更依赖 SKILL.md 里的说明文字。不管哪种核心是让模型能判断“当前任务是否匹配”。3.2 执行层skill 内部怎么干活执行层是 skill 的主体决定了它实际能做什么。常见结构有三种。第一种是纯提示词型skill 内部就是一段精心设计的 prompt让模型按固定格式输出。比如“分镜生成”skill输入一个故事梗概输出分镜表格。这种 skill 不需要外部工具实现简单适合创意类、格式化类任务。第二种是工具编排型skill 内部调用多个外部工具按顺序或条件执行。比如“自动挖洞”skill这里指安全测试场景内部要调扫描工具、解析结果、生成报告。这种 skill 的关键是错误处理和中间状态管理任何一个步骤失败都要有兜底。第三种是混合型既有提示词逻辑又有工具调用。实际项目里大部分 skill 都是这种。比如“论文写作”skill先用提示词生成大纲再调文献检索工具再调格式化工具最后用提示词做润色。3.3 约束层让 skill 输出稳定可控约束层是很多人容易忽略的部分但它决定了 skill 能不能上生产。约束包括输出格式约束、内容边界约束、调用频率约束。输出格式约束最常用的是 JSON Schema。我建议所有需要被下游程序消费的 skill输出都用结构化格式不要用自然语言。自然语言看起来灵活但解析起来是噩梦。用 JSON Schema 还有个好处模型在生成时会被约束减少胡编乱造。内容边界约束是告诉 skill“什么不能做”。比如客服 skill 不能承诺退款金额医疗 skill 不能给诊断结论。这些约束要写进 skill 的说明里并且在测试时专门验证。调用频率约束是防止 skill 被滥用。比如调用外部 API 的 skill要限制每分钟调用次数避免触发限流或产生高额费用。这个通常在编排层做但 skill 自己也可以记录调用状态。3.4 一个最小可用 skill 的结构示例下面是一个通用结构的伪代码示例不绑定具体框架你可以按自己用的平台调整。name: generate_weekly_report description: | 根据用户提供的时间范围查询工作数据并生成周报。 仅用于周期性工作总结不用于实时数据查询或单次任务跟踪。 trigger: intent: 生成周报 keywords: [周报, 工作总结, 本周报告] input_schema: type: object properties: start_date: type: string format: date end_date: type: string format: date required: [start_date, end_date] steps: - id: query_data tool: database_query params: sql: SELECT * FROM tasks WHERE date BETWEEN {{start_date}} AND {{end_date}} - id: summarize prompt: | 根据以下任务数据生成一份简洁的周报摘要 {{query_data.result}} - id: format tool: markdown_formatter params: content: {{summarize.output}} output_schema: type: object properties: report_markdown: type: string task_count: type: integer constraints: - 不得包含未在数据中出现的任务 - 输出必须为合法 Markdown这个结构里元信息、执行步骤、输入输出、约束都齐了。实际写的时候步骤可以更复杂但骨架就是这样。4. 实操落地从零跑通一个 skill 的完整流程4.1 环境准备与依赖选择动手之前先把环境理清楚。如果你用 Google Cloud 这套典型组合是 GKE 做运行环境、Genkit 做 Agent 编排、Cloud Run 或 Cloud Functions 做工具后端。如果只是本地实验Node.js 加 Genkit CLI 就够了不需要上 GKE。我个人的建议是实验阶段本地跑验证阶段上 Cloud Run生产阶段再考虑 GKE。一上来就上 GKE 容易把时间花在集群配置上而不是 skill 本身。GKE 的价值在于大规模、多 Agent、需要精细资源隔离的场景小项目用不上。依赖方面Genkit 需要 Node.js 18 以上Python 版本也有但生态稍弱。如果你用 Anthropic 的 Agent Skills基本就是文件系统加一个支持读取文件的 Agent 运行时依赖更少。codex skills 则依赖对应的 CLI 或 SDK。4.2 定义 skill 的输入输出契约这一步是实操里最关键的也是最容易偷懒的。我的做法是先写测试用例再写 skill。比如要做一个“分镜生成”skill我先写三个输入一个简单故事、一个复杂故事、一个边界情况比如只有一句话。然后写出我期望的输出格式。这样 skill 写完后直接跑测试用例验证。输入输出契约要明确到字段级别。日期用什么格式数字是整数还是浮点数字符串有没有长度限制枚举值有哪些。这些不写清楚模型就会自由发挥下游程序就会崩。提示如果 skill 输出要给前端渲染建议在契约里直接定义好前端需要的字段避免前端再做一层转换。我踩过的坑是 skill 输出和前端期望差一个字段名联调时查了半天。4.3 编写 skill 的执行逻辑执行逻辑的编写分两种情况。如果是纯提示词型重点在 prompt 的设计。我的经验是给例子比给规则更有效。与其写“输出要简洁”不如给一个简洁输出的例子。模型对例子的模仿能力远强于对抽象规则的理解。如果是工具编排型重点在步骤拆分和错误处理。每个步骤要有明确的输入输出步骤之间用变量传递。错误处理要覆盖三种情况工具调用失败、工具返回空结果、工具返回格式不符合预期。每种情况都要有对应的兜底逻辑。Genkit 里可以用 flow 来编排每个 step 是一个函数flow 负责串联。Anthropic 的 Agent Skills 更偏向让模型自己按 SKILL.md 的说明执行所以说明文档要写得非常细把每一步做什么、遇到问题怎么办都写清楚。4.4 注册与路由配置skill 写完后要注册到 Agent 的路由表里。这一步决定了 Agent 能不能找到它。注册信息包括 skill 名称、描述、触发条件、优先级。优先级很重要。当多个 skill 都可能匹配时优先级高的先触发。比如“生成周报”和“查询任务”都可能匹配“本周任务”这个输入但前者是生成报告后者是查数据要根据用户意图区分。我的做法是给每个 skill 设一个优先级分数路由时按分数排序分数相同再让模型判断。路由配置还要考虑 fallback。当没有 skill 匹配时Agent 应该怎么回应。我一般设一个默认 skill负责友好提示并引导用户重新描述需求而不是直接报错。4.5 测试与验证测试分三层。第一层是单元测试单独测每个 skill 的输入输出不经过 Agent 路由。第二层是集成测试测 Agent 能不能正确路由到 skill。第三层是端到端测试模拟真实用户对话看整个链路是否顺畅。我重点说第二层因为这是最容易出问题的地方。路由测试要覆盖明确匹配、模糊匹配、多 skill 竞争、无匹配四种情况。每种情况准备至少五个测试用例。模糊匹配尤其重要因为用户不会按你预设的关键词说话。端到端测试建议用真实对话记录而不是自己编的测试用例。真实用户的表达方式千奇百怪自己编的用例往往太“标准”测不出问题。5. 常见问题与排查技巧实录5.1 路由不准Agent 总是选错 skill这是最高频的问题。原因通常有三个描述写得太模糊、多个 skill 描述重叠、触发条件太宽泛。排查方法把 Agent 的路由日志打出来看它在每个输入上给各个 skill 打的分。如果两个 skill 分数接近说明描述需要区分。如果某个 skill 在所有输入上分数都高说明它的触发条件太宽。解决技巧在描述里加入“不适用于”的说明。比如“生成周报”skill 的描述里加一句“不适用于查询单条任务详情”能明显减少误触发。另外给 skill 加负面关键词也有效比如“周报”触发“单条”“详情”抑制。5.2 输出格式不稳定有时 JSON 有时自然语言这是约束层没做好。模型在生成时如果没有强约束会倾向于用自然语言。解决方法是在 prompt 里明确要求 JSON并且给出 schema。如果还是不稳定可以用 few-shot 例子给两三个输入输出对模型会模仿格式。Genkit 里可以用 output schema 强制约束Anthropic 的 skill 则需要在说明里反复强调格式要求。我试过在说明里加一句“输出必须是合法 JSON不要包含任何解释文字”效果比单纯说“输出 JSON”好很多。5.3 工具调用失败skill 执行到一半卡住工具调用失败的原因很多网络问题、API 限流、参数错误、权限不足。排查时先看错误信息再定位是哪个步骤。我的做法是给每个工具调用加超时和重试。超时设 10 秒重试 2 次重试间隔 1 秒。如果还失败就返回一个友好的错误信息而不是让整个 skill 崩掉。错误信息要包含失败步骤和原因方便排查。注意重试要区分错误类型。网络超时可以重试参数错误重试没用权限问题重试也没用。无脑重试只会浪费调用次数。5.4 上下文丢失多轮对话中 skill 忘记之前的信息这是状态管理问题。skill 本身通常是无状态的状态要由 Agent 的 memory 层管理。如果 memory 没设计好多轮对话中 skill 就看不到历史信息。解决方法是在 skill 的输入里显式传入必要的上下文。比如“生成周报”skill 需要知道用户之前说的日期范围那就把这个信息作为输入参数传进去而不是让 skill 自己去猜。Genkit 里可以用 session 管理上下文Anthropic 的 skill 则依赖 Agent 运行时提供的上下文。5.5 常见问题速查表问题现象可能原因排查方法解决技巧路由选错 skill描述模糊或重叠看路由打分日志加“不适用于”说明和负面关键词输出格式不稳定约束不足检查 prompt 和 schema加 few-shot 例子和强制格式说明工具调用失败网络/限流/参数/权限看错误信息和失败步骤加超时重试区分错误类型多轮对话丢上下文memory 未传递检查 skill 输入参数显式传入必要上下文skill 执行超时步骤太多或工具太慢看各步骤耗时拆分 skill 或优化工具输出内容越界边界约束缺失检查约束层加内容边界说明并测试验证6. 进阶玩法让 skills 真正产生复利6.1 skill 的组合与嵌套单个 skill 能做的事有限真正有价值的是 skill 组合。比如“自动挖洞”可以拆成“信息收集”“漏洞扫描”“结果验证”“报告生成”四个 skill主 Agent 按顺序调用。这样每个 skill 可以独立优化也可以被其他流程复用。嵌套是指一个 skill 内部调用另一个 skill。比如“论文写作”skill 内部调用“文献检索”skill 和“格式化”skill。嵌套要注意避免循环调用A 调 BB 又调 A会死循环。我的做法是给 skill 调用加深度限制超过三层就报错。6.2 skill 的版本管理与灰度发布skill 是要迭代的改坏了会影响线上。所以要有版本管理。我的做法是每个 skill 带版本号路由时可以选择版本。新版本先灰度只让部分流量走观察一段时间没问题再全量。灰度期间要重点看三个指标路由准确率、执行成功率、输出合格率。任何一个下降超过 5%就回滚。这个机制看起来麻烦但比出事后再补救省事得多。6.3 skill 的监控与持续优化上线不是终点。要持续监控 skill 的表现收集失败案例定期优化。我一般每周看一次失败日志把高频失败原因归类然后针对性改进。监控指标包括调用次数、成功率、平均耗时、路由准确率、用户满意度如果有反馈渠道。这些指标要可视化方便快速发现问题。Genkit 自带一些监控能力GKE 上可以用 Cloud Monitoring 做更细的观测。6.4 从个人 skill 到团队 skill 库一个人写的 skill 是个人资产团队共享的 skill 才是组织资产。要建 skill 库需要统一命名规范、描述模板、测试标准、发布流程。这样别人用你的 skill 时不用猜看描述就知道怎么用。我建议 skill 库按领域分类比如“数据处理”“内容生成”“系统操作”“安全测试”。每个 skill 配一个 README写清楚用途、输入输出、示例、注意事项。这样新成员上手快老成员也不会重复造轮子。7. 我踩过的坑和几条实在建议第一个坑是过早追求通用。一开始就想做一个什么都能干的 skill结果什么都干不好。后来改成每个 skill 只干一件事反而好维护。通用性是组合出来的不是单个 skill 设计出来的。第二个坑是忽略测试。觉得 skill 能跑就行结果上线后各种边界情况出问题。后来强制自己先写测试用例再写 skill问题少了很多。测试用例不用多每个 skill 五到十个就够但要覆盖正常、边界、异常三种情况。第三个坑是描述写得太技术。用了一堆专业术语结果 Agent 理解不了。后来改成用大白话写描述就像跟同事解释一样路由准确率反而提升了。模型对自然语言的理解比对术语的理解好。第四个坑是不做版本管理。改 skill 直接改线上出问题没法回滚。后来加了版本号和灰度心里踏实多了。最后分享一个小技巧给每个 skill 写一个“反例”。就是明确写出“这个 skill 不适用于什么场景”。这个反例在路由时非常有用能挡掉大量误触发。我试过加了反例之后路由准确率从 70% 多提升到 90% 以上。这个方向后续还可以扩展的地方很多比如 skill 的自动生成、skill 之间的自动编排、基于使用数据的 skill 推荐。但不管怎么扩展核心还是那句话把能力拆小、把边界写清、把测试做足。做到这三点skills 这套东西就能真正用起来而不是停留在概念层面。