1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题加上正文和关键词都是空的我其实是有点懵的。但结合热搜词里那一串——Google Cloud、AI agents、GKE、Genkit、claude agent skills、codex skills、skills开发、skills安装包——基本可以判断这里说的不是泛泛的技能概念而是AI Agent 生态里的技能包机制把一段可复用的能力提示词、工具调用、工作流、脚本封装成一个独立单元让 Agent 按需加载、按需执行。这个方向最近确实火。原因也不复杂大模型本身的能力已经够强了真正卡住落地的是怎么让模型稳定地干一件具体的事。你直接丢一句帮我分析这份财报模型可能给你一段泛泛而谈但如果你给它一个封装好的 skill——里面写死了数据读取方式、分析框架、输出格式——结果就稳定得多。skills 本质上就是把提示工程升级成能力工程。我自己的理解是skills 解决的是三个层面的问题。第一层是复用同一个能力不用每次重新写提示词封装一次到处调用。第二层是组合单个 skill 只干一件事多个 skill 串起来就能完成复杂任务这跟微服务的思路很像。第三层是可控skill 里可以约束输入输出、限制工具权限、加校验逻辑让 Agent 的行为边界清晰。所以这篇内容我打算按一个真正落地过 skills 的从业者的视角来写把概念、架构、开发、调试、踩坑、选型都讲透。不管你是刚听说 skills 想入门还是已经在用 Claude、Codex 这类工具想深入定制应该都能找到能直接抄的东西。下面我会结合 Google Cloud 那套GKE Genkit和 Claude/Codex 的 agent skills 两条线来讲因为这两条线目前是社区里讨论最多、资料最杂的。2. skills 的核心机制为什么它不是高级提示词2.1 一个 skill 的最小构成很多人第一次接触 skills会以为它就是把提示词存成文件。这个理解不算错但太浅了。一个能真正跑起来的 skill通常包含四个部分元信息metadata名称、描述、触发条件。这部分决定了 Agent 什么时候会想起用这个 skill。描述写得含糊Agent 就永远不触发写得精准命中率立刻上来。指令体instructions具体要做什么、按什么步骤做、输出什么格式。这是 skill 的大脑。资源resources脚本、模板、参考文档、示例数据。skill 可以按需读取这些文件而不是把所有内容都塞进上下文。工具声明tools这个 skill 允许调用哪些外部能力比如读文件、发请求、查数据库。我实测下来元信息里的 description 是最容易被低估的部分。它相当于 skill 的广告语Agent 在决定用不用某个 skill 时主要就看这段描述。我见过太多人把描述写成处理数据结果 Agent 从来不调用改成当用户提供 CSV 文件并需要按月份聚合销售额时使用命中率立刻不一样。2.2 渐进式披露skills 最聪明的设计skills 相比把一大段提示词全塞进去最大的优势是渐进式披露progressive disclosure。这个概念值得单独讲。传统做法是把所有指令、所有示例、所有规则一次性写进系统提示上下文又长又贵模型还容易抓不住重点。skills 的做法是分三层第一层只加载 skill 的名称和描述让 Agent 知道有这么个能力存在。第二层当 Agent 判断需要用到时才加载完整的指令体。第三层指令体里如果需要引用某个模板或脚本再按需读取那个文件。这个设计的好处是上下文占用极小。你可以挂几十个 skill平时只占几百 token 的描述真正用哪个才展开哪个。我做过对比同样 20 个能力全塞进系统提示大概要 8000 token用 skills 机制常驻部分不到 800 token差距非常明显。提示设计 skill 时把什么时候用写进 description把怎么用写进指令体把用到才需要的东西放进资源文件。这个分层是 skills 高效的根本。2.3 skills 和 function calling、MCP 的区别社区里经常有人把 skills、function calling、MCP 混为一谈这里必须掰清楚否则选型会走弯路。机制本质解决的问题典型场景Function Calling模型输出结构化调用请求让模型能触发外部函数查天气、算数、调 APIMCP标准化的工具/资源接入协议让工具能被统一发现和调用接数据库、接文件系统Skills封装好的能力单元含指令资源工具让复杂任务可复用、可组合财报分析、代码审查、分镜生成简单说function calling 是手MCP 是插座标准skills 是整套工具包。一个 skill 内部可以调用多个 function也可以依赖 MCP 提供的工具。它们不是竞争关系是不同层次的东西。理解这一点后面做架构设计就不会乱。3. 两条主流路线Google Cloud 系与 Claude/Codex 系3.1 Google Cloud 路线GKE Genkit 的组合热搜词里出现了 Google Cloud、GKE、Genkit这条线是云原生 AI 编排的思路。Genkit 是 Google 出的 AI 应用开发框架它的定位是帮你把提示词、工具、流程、评估组织成可维护的代码。在 Genkit 里一个能力单元通常表现为一个flow或者一个tool可以本地调试也可以部署到 Cloud Run 或 GKE 上跑。GKE 在这里的角色是运行载体。当你的 Agent 需要稳定、可扩展地跑在生产环境尤其是要处理并发请求、要做资源隔离、要接企业内部网络时GKE 这种容器编排平台就派上用场了。我自己的经验是开发阶段用 Genkit 本地跑验证逻辑上线阶段容器化丢到 GKE用 HPA 做弹性伸缩。这个组合的好处是开发体验和运维能力兼顾。具体到 skills 的落地Google Cloud 这条线的典型做法是用 Genkit 定义每个 skill 对应的 flow输入输出用 schema 约束死。把 flow 暴露成 HTTP 端点或者注册成 Agent 可调用的 tool。容器化后部署到 GKE配置好资源限制和健康检查。用 Cloud Logging 和 Trace 做可观测性看每个 skill 的调用耗时和失败率。这套流程听起来重但对于要上生产、要对接企业系统的场景是必要的。个人玩票的话本地 Genkit 就够了。3.2 Claude / Codex 路线文件系统式的 agent skills另一条线是 Claude 和 Codex 这类工具里的 agent skills形态更轻——本质是一个文件夹里面有SKILL.md作为入口加上若干资源文件。这种设计的哲学是skill 即文件。你不需要写代码、不需要部署只要按约定组织好目录结构Agent 就能识别和加载。我实测下来这种方式的入门门槛极低但要做好也不容易因为全靠指令写得好不好。一个典型的目录结构大概是这样my-skill/ ├── SKILL.md # 入口含元信息和指令 ├── templates/ # 输出模板 ├── scripts/ # 可执行脚本 └── references/ # 参考资料SKILL.md顶部的元信息用 YAML frontmatter 写类似--- name: financial-report-analyzer description: 当用户提供财报文件并需要提取关键财务指标、生成分析摘要时使用 ---下面才是正文指令。这个格式的好处是人和机器都能读你改起来直观Agent 解析也简单。3.3 两条路线怎么选这个问题我被问过很多次我的答案一直是看你的部署场景和团队构成。如果你是个人开发者、做原型、想快速验证想法Claude/Codex 的文件式 skills 更快改一个 markdown 就生效。如果你要上生产、要对接企业系统、要多人协作、要做版本管理和灰度发布Google Cloud 那条线更稳因为它是代码化的、可测试的、可 CI/CD 的。如果你两边都要可以用文件式 skills 做原型验证有效后用 Genkit 重写成 flow再部署到 GKE。我自己就是这么干的原型阶段省时间上线阶段保稳定。注意不要一上来就追求生产级架构。我见过太多人花两周搭 GKE 集群结果 skill 逻辑本身还没跑通。先用最轻的方式把能力验证出来再考虑工程化。4. 从零开发一个 skill完整实操链路4.1 先想清楚这个 skill 的边界在哪动手写之前最重要的一步是定义边界。一个 skill 只干一件事干好一件事。我踩过的最大坑就是贪多——一个 skill 里塞了数据读取、清洗、分析、可视化、报告生成五件事结果 Agent 调用时经常在中途跑偏输出格式也不稳定。正确的做法是拆。比如财报分析这个需求我会拆成read-financial-file只负责读取文件、识别格式、返回结构化数据。extract-metrics只负责从结构化数据里提取关键指标。generate-analysis只负责基于指标生成分析文字。format-report只负责套模板输出最终报告。每个 skill 的输入输出都定义清楚串起来就是完整流程。这样拆的好处是每个环节都能单独测试、单独替换。哪天你觉得分析逻辑不好只改generate-analysis就行不影响其他部分。4.2 写 description 的实战技巧description 是 skill 的触发开关我总结了几个写法要点写场景不写功能。不要写分析财务数据要写当用户上传财报 PDF 并要求提取营收、利润、增长率等指标时使用。包含触发关键词。用户可能会说财报年报financial report10-K把这些词自然融进描述里。说明不适用的情况。比如不适用于实时股价查询能减少误触发。长度控制在 1-3 句。太短信息不够太长浪费上下文。我做过一个 A/B 测试同一个 skill描述从处理文档改成当用户提供 PDF 或 Word 文档并需要提取其中的表格数据时使用触发准确率从大概 40% 提到了 85% 以上。这个投入产出比非常高。4.3 指令体的结构让模型照着做而不是猜着做指令体最忌讳写成一大段散文。模型读散文容易漏细节读结构化指令就稳得多。我通常按这个结构写目标一句话说清这个 skill 要产出什么。输入明确需要哪些参数格式是什么。步骤编号列出每一步做什么越具体越好。输出格式给出确切的模板或 schema。异常处理遇到缺数据、格式错误时怎么办。示例给一两个输入输出样例。其中输出格式和示例是最能提升稳定性的。你给一个确切的 JSON schema模型就不会自由发挥你给一个完整的输入输出样例模型就有了模仿对象。我实测下来加了示例之后输出格式的合规率能从 70% 提到 95% 以上。4.4 资源文件怎么组织资源文件的原则是用到才加载。常见的几类模板文件输出用的 markdown、HTML、JSON 模板。脚本文件需要精确计算或确定性处理的逻辑用脚本而不是让模型算。参考文档领域知识、规则手册、术语表。示例数据few-shot 用的输入输出对。这里有个重要经验凡是需要精确、确定性结果的部分一律用脚本不要交给模型。比如金额计算、日期处理、格式转换模型容易出错脚本不会。skill 的指令体里写调用 scripts/calculate.py 完成计算比写请计算总额可靠得多。5. 调试与测试skills 最容易翻车的地方5.1 触发失败Agent 根本不用你的 skill这是最高频的问题。表现是你明明写了 skillAgent 却自己硬答不调用。排查链路我一般是这样的先看 description。是不是写得太泛是不是没包含用户会说的关键词这是 80% 的原因。再看 skill 数量。挂太多 skill描述之间互相干扰Agent 选择困难。我建议单个 Agent 常驻 skill 控制在 10-15 个以内多了就分组。看描述之间的重叠。两个 skill 描述太像Agent 会犹豫。要么合并要么把边界写得更清楚。看系统提示。有些框架需要在系统提示里显式告诉模型你有 skills 可用优先使用。我遇到过一次特别隐蔽的description 里用了分析这个词结果和另一个数据分析skill 撞了两个都不触发。后来把前者改成解读财报文本并生成叙述性结论问题解决。5.2 执行跑偏调用了但结果不对触发没问题但输出不符合预期通常是这几个原因指令不够具体。模型在合理发挥你需要把步骤写死。缺少输出约束。没给 schema 或模板模型自由发挥。上下文里塞了干扰信息。skill 加载时把无关内容也带进来了。模型能力不够。复杂推理任务小模型确实做不好换大模型或拆步骤。我的排查方法是逐步打印中间结果。在 skill 的每个步骤后加一个日志看模型在哪一步开始偏。定位到具体步骤后针对性加强那一步的指令或加示例。5.3 一个可复用的测试方法我给自己定的规矩是每个 skill 上线前必须过三关。测试类型目的方法正向测试正常输入能否正确触发并输出准备 5-10 个典型输入检查触发和输出负向测试不该触发时是否安静准备 5 个无关输入确认不误触发边界测试异常输入是否优雅处理空输入、超长输入、格式错误输入正向测试看能力负向测试看精度边界测试看健壮性。三关都过我才敢把它放进生产流程。这套方法帮我挡掉了很多看起来能用、实际一用就崩的 skill。提示测试用例要沉淀下来每次改 skill 都重跑一遍。我吃过改了一处指令、结果另一个场景挂掉的亏回归测试能救命。6. 组合与编排让多个 skill 协同干活6.1 串行编排像流水线一样最简单的组合是串行skill A 的输出作为 skill B 的输入。比如读取文件 → 提取指标 → 生成分析 → 格式化输出。串行的关键是接口对齐。A 的输出格式必须和 B 的输入格式严格匹配。我的做法是给每个 skill 定义明确的输入输出 schema串起来之前先做一次接口校验确保字段名、类型、必填项都对得上。这一步偷懒后面调试会加倍还回来。6.2 并行编排能同时干的别排队有些 skill 之间没有依赖可以并行。比如分析一份财报时提取财务指标和提取管理层讨论可以同时跑最后合并。并行能显著缩短总耗时尤其是调用外部服务或大模型时。实现上Google Cloud 那条线可以用 Genkit 的并行 flow文件式 skills 那条线通常靠 Agent 自己判断能不能并行。我一般会在编排层显式声明依赖关系让框架知道哪些能并行。6.3 编排层要不要自己写这是个实际问题。我的经验是简单场景2-3 个 skill 串行让 Agent 自己编排就行不用额外写代码。中等场景有分支、有循环、有并行写一个轻量编排层用代码控制流程skill 只负责单点能力。复杂场景多 Agent 协作、长流程、要断点续跑上专门的编排框架比如 Genkit 的 flow 或者工作流引擎。核心原则是能用代码控制的确定性流程就别交给模型自由发挥。模型适合做判断和生成不适合做流程控制。把流程控制权拿回代码里稳定性会好很多。7. 生产化从能跑到跑得稳7.1 可观测性你必须知道 skill 在干什么skill 上了生产最怕的是黑盒。用户说结果不对你完全不知道中间发生了什么。所以可观测性是必须的。我通常会记录这几类信息触发日志哪个 skill 被触发、触发时的输入是什么。执行日志每个步骤的耗时、中间结果、是否报错。输出日志最终输出、是否符合 schema。成本日志token 消耗、外部调用次数。这些数据攒起来能回答很多问题哪个 skill 最慢、哪个最容易失败、哪个最费钱。我靠这些数据优化过好几个 skill把平均耗时砍掉了一半。7.2 版本管理与灰度skill 是会迭代的。改指令、换模型、调参数都可能影响效果。所以版本管理不能省。我的做法是每个 skill 带版本号改动走新版本 → 灰度 → 全量的流程。灰度阶段对比新旧版本的触发率、成功率、输出质量确认没问题再全量。文件式 skills 可以用 git 管理代码式 skills 走正常的 CI/CD。7.3 成本控制skills 也会烧钱skills 用起来爽但 token 消耗和外部调用都是钱。几个控制手段精简指令体。能一句话说清就别写三段。资源按需加载。别把所有参考文档都塞进上下文。缓存重复结果。同样的输入没必要重复算。小模型干简单活。分类、提取这类任务小模型够用就别上大模型。我算过一笔账一个设计良好的 skill比每次重新写提示词的方式token 消耗能省 60% 以上因为指令和资源都是复用的不用每次重写。8. 我踩过的坑和几条实在建议8.1 别把 skill 当万能药skills 不是所有问题的最优解。如果一件事只做一次写个 skill 反而麻烦如果一件事逻辑极其简单直接写提示词更快。skills 的价值在复用和组合用不到这两点就别硬上。8.2 指令要啰嗦一点新手写 skill 最大的问题是太简洁。他们觉得模型能理解意图所以写得含糊。但实测下来指令写得越具体、越啰嗦效果越稳。把模型当成一个聪明但没背景知识的新人你需要把上下文、步骤、格式都交代清楚。8.3 先手动跑通再封装我见过有人直接写 skill写完发现逻辑本身就不对。正确顺序是先手动把这件事做一遍确认流程可行再把流程封装成 skill。手动跑通的过程其实就是在梳理指令体的过程。8.4 定期清理僵尸 skillskill 越攒越多很多已经不用了但还挂在 Agent 上干扰触发。我建议每个月清理一次把不用的删掉或归档。保持 skill 库精简触发准确率会明显提升。8.5 社区资源怎么用热搜里提到的skills 大全skills 推荐github skills这些确实能找到不少现成的 skill。我的用法是拿来当参考不当成品。别人的 skill 是在别人的场景下调优的直接拿来用往往水土不服。看它的结构、看它的 description 怎么写、看它的指令怎么组织然后按自己的需求重写这才是正确姿势。最后分享一个我自己的习惯每做一个新 skill我都会在SKILL.md末尾留一段变更记录写清楚每次改了什么、为什么改、效果如何。这个习惯看起来小但几个月后回头看能帮你快速回忆起当初的设计意图避免重复踩坑。skills 这东西本质上是在积累你自己的能力资产管理好它长期收益很大。 AI Agent技能包实战：从概念到生产级部署
1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题加上正文和关键词都是空的我其实是有点懵的。但结合热搜词里那一串——Google Cloud、AI agents、GKE、Genkit、claude agent skills、codex skills、skills开发、skills安装包——基本可以判断这里说的不是泛泛的技能概念而是AI Agent 生态里的技能包机制把一段可复用的能力提示词、工具调用、工作流、脚本封装成一个独立单元让 Agent 按需加载、按需执行。这个方向最近确实火。原因也不复杂大模型本身的能力已经够强了真正卡住落地的是怎么让模型稳定地干一件具体的事。你直接丢一句帮我分析这份财报模型可能给你一段泛泛而谈但如果你给它一个封装好的 skill——里面写死了数据读取方式、分析框架、输出格式——结果就稳定得多。skills 本质上就是把提示工程升级成能力工程。我自己的理解是skills 解决的是三个层面的问题。第一层是复用同一个能力不用每次重新写提示词封装一次到处调用。第二层是组合单个 skill 只干一件事多个 skill 串起来就能完成复杂任务这跟微服务的思路很像。第三层是可控skill 里可以约束输入输出、限制工具权限、加校验逻辑让 Agent 的行为边界清晰。所以这篇内容我打算按一个真正落地过 skills 的从业者的视角来写把概念、架构、开发、调试、踩坑、选型都讲透。不管你是刚听说 skills 想入门还是已经在用 Claude、Codex 这类工具想深入定制应该都能找到能直接抄的东西。下面我会结合 Google Cloud 那套GKE Genkit和 Claude/Codex 的 agent skills 两条线来讲因为这两条线目前是社区里讨论最多、资料最杂的。2. skills 的核心机制为什么它不是高级提示词2.1 一个 skill 的最小构成很多人第一次接触 skills会以为它就是把提示词存成文件。这个理解不算错但太浅了。一个能真正跑起来的 skill通常包含四个部分元信息metadata名称、描述、触发条件。这部分决定了 Agent 什么时候会想起用这个 skill。描述写得含糊Agent 就永远不触发写得精准命中率立刻上来。指令体instructions具体要做什么、按什么步骤做、输出什么格式。这是 skill 的大脑。资源resources脚本、模板、参考文档、示例数据。skill 可以按需读取这些文件而不是把所有内容都塞进上下文。工具声明tools这个 skill 允许调用哪些外部能力比如读文件、发请求、查数据库。我实测下来元信息里的 description 是最容易被低估的部分。它相当于 skill 的广告语Agent 在决定用不用某个 skill 时主要就看这段描述。我见过太多人把描述写成处理数据结果 Agent 从来不调用改成当用户提供 CSV 文件并需要按月份聚合销售额时使用命中率立刻不一样。2.2 渐进式披露skills 最聪明的设计skills 相比把一大段提示词全塞进去最大的优势是渐进式披露progressive disclosure。这个概念值得单独讲。传统做法是把所有指令、所有示例、所有规则一次性写进系统提示上下文又长又贵模型还容易抓不住重点。skills 的做法是分三层第一层只加载 skill 的名称和描述让 Agent 知道有这么个能力存在。第二层当 Agent 判断需要用到时才加载完整的指令体。第三层指令体里如果需要引用某个模板或脚本再按需读取那个文件。这个设计的好处是上下文占用极小。你可以挂几十个 skill平时只占几百 token 的描述真正用哪个才展开哪个。我做过对比同样 20 个能力全塞进系统提示大概要 8000 token用 skills 机制常驻部分不到 800 token差距非常明显。提示设计 skill 时把什么时候用写进 description把怎么用写进指令体把用到才需要的东西放进资源文件。这个分层是 skills 高效的根本。2.3 skills 和 function calling、MCP 的区别社区里经常有人把 skills、function calling、MCP 混为一谈这里必须掰清楚否则选型会走弯路。机制本质解决的问题典型场景Function Calling模型输出结构化调用请求让模型能触发外部函数查天气、算数、调 APIMCP标准化的工具/资源接入协议让工具能被统一发现和调用接数据库、接文件系统Skills封装好的能力单元含指令资源工具让复杂任务可复用、可组合财报分析、代码审查、分镜生成简单说function calling 是手MCP 是插座标准skills 是整套工具包。一个 skill 内部可以调用多个 function也可以依赖 MCP 提供的工具。它们不是竞争关系是不同层次的东西。理解这一点后面做架构设计就不会乱。3. 两条主流路线Google Cloud 系与 Claude/Codex 系3.1 Google Cloud 路线GKE Genkit 的组合热搜词里出现了 Google Cloud、GKE、Genkit这条线是云原生 AI 编排的思路。Genkit 是 Google 出的 AI 应用开发框架它的定位是帮你把提示词、工具、流程、评估组织成可维护的代码。在 Genkit 里一个能力单元通常表现为一个flow或者一个tool可以本地调试也可以部署到 Cloud Run 或 GKE 上跑。GKE 在这里的角色是运行载体。当你的 Agent 需要稳定、可扩展地跑在生产环境尤其是要处理并发请求、要做资源隔离、要接企业内部网络时GKE 这种容器编排平台就派上用场了。我自己的经验是开发阶段用 Genkit 本地跑验证逻辑上线阶段容器化丢到 GKE用 HPA 做弹性伸缩。这个组合的好处是开发体验和运维能力兼顾。具体到 skills 的落地Google Cloud 这条线的典型做法是用 Genkit 定义每个 skill 对应的 flow输入输出用 schema 约束死。把 flow 暴露成 HTTP 端点或者注册成 Agent 可调用的 tool。容器化后部署到 GKE配置好资源限制和健康检查。用 Cloud Logging 和 Trace 做可观测性看每个 skill 的调用耗时和失败率。这套流程听起来重但对于要上生产、要对接企业系统的场景是必要的。个人玩票的话本地 Genkit 就够了。3.2 Claude / Codex 路线文件系统式的 agent skills另一条线是 Claude 和 Codex 这类工具里的 agent skills形态更轻——本质是一个文件夹里面有SKILL.md作为入口加上若干资源文件。这种设计的哲学是skill 即文件。你不需要写代码、不需要部署只要按约定组织好目录结构Agent 就能识别和加载。我实测下来这种方式的入门门槛极低但要做好也不容易因为全靠指令写得好不好。一个典型的目录结构大概是这样my-skill/ ├── SKILL.md # 入口含元信息和指令 ├── templates/ # 输出模板 ├── scripts/ # 可执行脚本 └── references/ # 参考资料SKILL.md顶部的元信息用 YAML frontmatter 写类似--- name: financial-report-analyzer description: 当用户提供财报文件并需要提取关键财务指标、生成分析摘要时使用 ---下面才是正文指令。这个格式的好处是人和机器都能读你改起来直观Agent 解析也简单。3.3 两条路线怎么选这个问题我被问过很多次我的答案一直是看你的部署场景和团队构成。如果你是个人开发者、做原型、想快速验证想法Claude/Codex 的文件式 skills 更快改一个 markdown 就生效。如果你要上生产、要对接企业系统、要多人协作、要做版本管理和灰度发布Google Cloud 那条线更稳因为它是代码化的、可测试的、可 CI/CD 的。如果你两边都要可以用文件式 skills 做原型验证有效后用 Genkit 重写成 flow再部署到 GKE。我自己就是这么干的原型阶段省时间上线阶段保稳定。注意不要一上来就追求生产级架构。我见过太多人花两周搭 GKE 集群结果 skill 逻辑本身还没跑通。先用最轻的方式把能力验证出来再考虑工程化。4. 从零开发一个 skill完整实操链路4.1 先想清楚这个 skill 的边界在哪动手写之前最重要的一步是定义边界。一个 skill 只干一件事干好一件事。我踩过的最大坑就是贪多——一个 skill 里塞了数据读取、清洗、分析、可视化、报告生成五件事结果 Agent 调用时经常在中途跑偏输出格式也不稳定。正确的做法是拆。比如财报分析这个需求我会拆成read-financial-file只负责读取文件、识别格式、返回结构化数据。extract-metrics只负责从结构化数据里提取关键指标。generate-analysis只负责基于指标生成分析文字。format-report只负责套模板输出最终报告。每个 skill 的输入输出都定义清楚串起来就是完整流程。这样拆的好处是每个环节都能单独测试、单独替换。哪天你觉得分析逻辑不好只改generate-analysis就行不影响其他部分。4.2 写 description 的实战技巧description 是 skill 的触发开关我总结了几个写法要点写场景不写功能。不要写分析财务数据要写当用户上传财报 PDF 并要求提取营收、利润、增长率等指标时使用。包含触发关键词。用户可能会说财报年报financial report10-K把这些词自然融进描述里。说明不适用的情况。比如不适用于实时股价查询能减少误触发。长度控制在 1-3 句。太短信息不够太长浪费上下文。我做过一个 A/B 测试同一个 skill描述从处理文档改成当用户提供 PDF 或 Word 文档并需要提取其中的表格数据时使用触发准确率从大概 40% 提到了 85% 以上。这个投入产出比非常高。4.3 指令体的结构让模型照着做而不是猜着做指令体最忌讳写成一大段散文。模型读散文容易漏细节读结构化指令就稳得多。我通常按这个结构写目标一句话说清这个 skill 要产出什么。输入明确需要哪些参数格式是什么。步骤编号列出每一步做什么越具体越好。输出格式给出确切的模板或 schema。异常处理遇到缺数据、格式错误时怎么办。示例给一两个输入输出样例。其中输出格式和示例是最能提升稳定性的。你给一个确切的 JSON schema模型就不会自由发挥你给一个完整的输入输出样例模型就有了模仿对象。我实测下来加了示例之后输出格式的合规率能从 70% 提到 95% 以上。4.4 资源文件怎么组织资源文件的原则是用到才加载。常见的几类模板文件输出用的 markdown、HTML、JSON 模板。脚本文件需要精确计算或确定性处理的逻辑用脚本而不是让模型算。参考文档领域知识、规则手册、术语表。示例数据few-shot 用的输入输出对。这里有个重要经验凡是需要精确、确定性结果的部分一律用脚本不要交给模型。比如金额计算、日期处理、格式转换模型容易出错脚本不会。skill 的指令体里写调用 scripts/calculate.py 完成计算比写请计算总额可靠得多。5. 调试与测试skills 最容易翻车的地方5.1 触发失败Agent 根本不用你的 skill这是最高频的问题。表现是你明明写了 skillAgent 却自己硬答不调用。排查链路我一般是这样的先看 description。是不是写得太泛是不是没包含用户会说的关键词这是 80% 的原因。再看 skill 数量。挂太多 skill描述之间互相干扰Agent 选择困难。我建议单个 Agent 常驻 skill 控制在 10-15 个以内多了就分组。看描述之间的重叠。两个 skill 描述太像Agent 会犹豫。要么合并要么把边界写得更清楚。看系统提示。有些框架需要在系统提示里显式告诉模型你有 skills 可用优先使用。我遇到过一次特别隐蔽的description 里用了分析这个词结果和另一个数据分析skill 撞了两个都不触发。后来把前者改成解读财报文本并生成叙述性结论问题解决。5.2 执行跑偏调用了但结果不对触发没问题但输出不符合预期通常是这几个原因指令不够具体。模型在合理发挥你需要把步骤写死。缺少输出约束。没给 schema 或模板模型自由发挥。上下文里塞了干扰信息。skill 加载时把无关内容也带进来了。模型能力不够。复杂推理任务小模型确实做不好换大模型或拆步骤。我的排查方法是逐步打印中间结果。在 skill 的每个步骤后加一个日志看模型在哪一步开始偏。定位到具体步骤后针对性加强那一步的指令或加示例。5.3 一个可复用的测试方法我给自己定的规矩是每个 skill 上线前必须过三关。测试类型目的方法正向测试正常输入能否正确触发并输出准备 5-10 个典型输入检查触发和输出负向测试不该触发时是否安静准备 5 个无关输入确认不误触发边界测试异常输入是否优雅处理空输入、超长输入、格式错误输入正向测试看能力负向测试看精度边界测试看健壮性。三关都过我才敢把它放进生产流程。这套方法帮我挡掉了很多看起来能用、实际一用就崩的 skill。提示测试用例要沉淀下来每次改 skill 都重跑一遍。我吃过改了一处指令、结果另一个场景挂掉的亏回归测试能救命。6. 组合与编排让多个 skill 协同干活6.1 串行编排像流水线一样最简单的组合是串行skill A 的输出作为 skill B 的输入。比如读取文件 → 提取指标 → 生成分析 → 格式化输出。串行的关键是接口对齐。A 的输出格式必须和 B 的输入格式严格匹配。我的做法是给每个 skill 定义明确的输入输出 schema串起来之前先做一次接口校验确保字段名、类型、必填项都对得上。这一步偷懒后面调试会加倍还回来。6.2 并行编排能同时干的别排队有些 skill 之间没有依赖可以并行。比如分析一份财报时提取财务指标和提取管理层讨论可以同时跑最后合并。并行能显著缩短总耗时尤其是调用外部服务或大模型时。实现上Google Cloud 那条线可以用 Genkit 的并行 flow文件式 skills 那条线通常靠 Agent 自己判断能不能并行。我一般会在编排层显式声明依赖关系让框架知道哪些能并行。6.3 编排层要不要自己写这是个实际问题。我的经验是简单场景2-3 个 skill 串行让 Agent 自己编排就行不用额外写代码。中等场景有分支、有循环、有并行写一个轻量编排层用代码控制流程skill 只负责单点能力。复杂场景多 Agent 协作、长流程、要断点续跑上专门的编排框架比如 Genkit 的 flow 或者工作流引擎。核心原则是能用代码控制的确定性流程就别交给模型自由发挥。模型适合做判断和生成不适合做流程控制。把流程控制权拿回代码里稳定性会好很多。7. 生产化从能跑到跑得稳7.1 可观测性你必须知道 skill 在干什么skill 上了生产最怕的是黑盒。用户说结果不对你完全不知道中间发生了什么。所以可观测性是必须的。我通常会记录这几类信息触发日志哪个 skill 被触发、触发时的输入是什么。执行日志每个步骤的耗时、中间结果、是否报错。输出日志最终输出、是否符合 schema。成本日志token 消耗、外部调用次数。这些数据攒起来能回答很多问题哪个 skill 最慢、哪个最容易失败、哪个最费钱。我靠这些数据优化过好几个 skill把平均耗时砍掉了一半。7.2 版本管理与灰度skill 是会迭代的。改指令、换模型、调参数都可能影响效果。所以版本管理不能省。我的做法是每个 skill 带版本号改动走新版本 → 灰度 → 全量的流程。灰度阶段对比新旧版本的触发率、成功率、输出质量确认没问题再全量。文件式 skills 可以用 git 管理代码式 skills 走正常的 CI/CD。7.3 成本控制skills 也会烧钱skills 用起来爽但 token 消耗和外部调用都是钱。几个控制手段精简指令体。能一句话说清就别写三段。资源按需加载。别把所有参考文档都塞进上下文。缓存重复结果。同样的输入没必要重复算。小模型干简单活。分类、提取这类任务小模型够用就别上大模型。我算过一笔账一个设计良好的 skill比每次重新写提示词的方式token 消耗能省 60% 以上因为指令和资源都是复用的不用每次重写。8. 我踩过的坑和几条实在建议8.1 别把 skill 当万能药skills 不是所有问题的最优解。如果一件事只做一次写个 skill 反而麻烦如果一件事逻辑极其简单直接写提示词更快。skills 的价值在复用和组合用不到这两点就别硬上。8.2 指令要啰嗦一点新手写 skill 最大的问题是太简洁。他们觉得模型能理解意图所以写得含糊。但实测下来指令写得越具体、越啰嗦效果越稳。把模型当成一个聪明但没背景知识的新人你需要把上下文、步骤、格式都交代清楚。8.3 先手动跑通再封装我见过有人直接写 skill写完发现逻辑本身就不对。正确顺序是先手动把这件事做一遍确认流程可行再把流程封装成 skill。手动跑通的过程其实就是在梳理指令体的过程。8.4 定期清理僵尸 skillskill 越攒越多很多已经不用了但还挂在 Agent 上干扰触发。我建议每个月清理一次把不用的删掉或归档。保持 skill 库精简触发准确率会明显提升。8.5 社区资源怎么用热搜里提到的skills 大全skills 推荐github skills这些确实能找到不少现成的 skill。我的用法是拿来当参考不当成品。别人的 skill 是在别人的场景下调优的直接拿来用往往水土不服。看它的结构、看它的 description 怎么写、看它的指令怎么组织然后按自己的需求重写这才是正确姿势。最后分享一个我自己的习惯每做一个新 skill我都会在SKILL.md末尾留一段变更记录写清楚每次改了什么、为什么改、效果如何。这个习惯看起来小但几个月后回头看能帮你快速回忆起当初的设计意图避免重复踩坑。skills 这东西本质上是在积累你自己的能力资产管理好它长期收益很大。