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. 整体设计思路：为什么要把能力拆成 skills
2.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 调 B，B 又调 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 这套东西就能真正用起来，而不是停留在概念层面。
