1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里反复出现的 Google Cloud、Agent Skills、GKE、Genkit以及“claude agent skills”“codex skills”“skills开发”“skills安装包下载”这些词可以确定这里说的 skills 不是人类的能力而是给 AI Agent 使用的一套可插拔能力模块。简单说它是一组结构化的指令、工具描述和资源文件让一个通用的大模型在特定任务上表现得像一个受过训练的专才。它解决的问题很具体大模型本身什么都会一点但什么都不精。你让它写代码它能写但不符合你团队的规范你让它做数据分析它能做但不知道你公司的指标口径你让它处理工单它能处理但不懂你的业务分类。skills 就是把这些“隐性知识”显性化、模块化让 Agent 在需要的时候加载对应的能力包而不是每次都在提示词里重复交代。适合谁来参考三类人最需要关注。第一类是AI 应用开发者尤其是用 Genkit、LangChain 这类框架搭建 Agent 的人skills 可以直接作为能力层复用。第二类是技术团队负责人需要把团队内部的流程、规范、工具封装成 Agent 可调用的资产。第三类是重度 AI 工具用户比如用 Claude、Codex 写代码或做研究的人理解 skills 的结构后可以自己写一个专属技能包把重复劳动压缩掉。我自己的体会是skills 这个概念之所以在最近半年集中爆发是因为 Agent 从“能聊天”进入“能干活”阶段后大家发现光靠提示词工程已经不够了。提示词是临时的、易失的、不可版本管理的而 skills 是持久的、可复用的、可测试的。这个转变很像前端开发从写内联样式到组件化的过程一旦你习惯了组件化就再也回不去了。2. 核心思路拆解为什么是“技能包”而不是“大提示词”2.1 从提示词堆砌到能力模块化早期做 Agent 的人都有一个共同的痛点提示词越写越长最后变成几千字的“说明书”模型还是经常漏掉关键步骤。原因很简单上下文窗口是有限的注意力也是有限的。你把所有规则都塞进一个系统提示里模型在生成每个 token 时都要在全部规则里做一次隐式检索噪声太大。skills 的思路是把“什么时候用什么能力”和“这个能力具体怎么做”分开。主 Agent 只需要知道有哪些技能可用以及每个技能的触发条件具体执行时再把对应技能的详细指令加载进来。这就像公司里的岗位职责和操作手册的关系岗位职责告诉你找谁办事操作手册告诉那个人具体怎么操作。你不会把全公司的操作手册发给每一个新员工而是按需分发。这个设计带来的直接好处是上下文利用率大幅提升。一个技能包通常只包含几十到几百行的指令加上必要的工具定义和示例加载后占用的 token 很少。而主 Agent 的系统提示可以保持精简只保留路由逻辑和全局约束。实测下来同样一个复杂任务用技能包拆解后模型出错的概率比单一大提示词低很多尤其是在步骤超过五步的任务上。2.2 技能包的三个核心组成一个标准的 skill 通常包含三部分。第一部分是元数据包括技能名称、描述、触发关键词、适用场景。这部分是给主 Agent 看的用来判断是否加载这个技能。第二部分是指令正文也就是这个技能具体怎么执行包括步骤、注意事项、输出格式。第三部分是资源引用比如需要调用的工具、需要读取的模板文件、需要参考的示例数据。这三部分的分工很明确元数据负责“被找到”指令正文负责“被理解”资源引用负责“被执行”。很多人在写 skill 时容易犯的错误是把所有内容都塞进指令正文结果元数据写得含糊主 Agent 根本不知道该在什么时候加载它。我的经验是元数据里的描述要写得像一条搜索摘要包含用户可能说的原话和同义词这样路由才准。2.3 与 GKE、Genkit 的关系热搜词里出现 GKE 和 Genkit说明 skills 的落地场景和 Google Cloud 的 Agent 生态有关。GKE 提供的是运行环境Genkit 提供的是开发框架而 skills 是跑在这个环境里的能力单元。你可以把 GKE 理解成厂房Genkit 理解成生产线skills 理解成一个个可替换的模具。模具设计得好换产品的时候只需要换模具不需要重建生产线。这种分层的好处是技能可以独立迭代。今天发现某个技能的输出格式不对只需要改那个技能包重新部署即可不影响其他技能。如果所有逻辑都写在一个大提示词里改一处就可能影响全局回归测试的成本极高。我在实际项目里吃过这个亏一个提示词改了标点符号结果另一个不相关的任务开始胡言乱语排查了一整天才定位到。3. 核心细节解析一个 skill 到底怎么写3.1 元数据的设计要点元数据是 skill 的“门面”决定了它能不能被正确调用。我通常会把元数据写成 YAML 格式包含以下几个字段name、description、triggers、version、author。name 用英文短横线命名比如code-review-python不要用空格或中文。description 用一句话说清楚这个技能做什么以及什么时候用最好包含用户可能说的关键词。triggers 是一个列表列出触发这个技能的典型用户输入。比如一个代码审查技能triggers 可以写[review my code, check this PR, 代码审查, 帮我看看这段代码]。这里要注意中英文都要覆盖因为用户可能混着说。version 字段很多人会忽略但在团队协作里非常重要技能更新后如果 Agent 还在用旧版本输出会不一致。提示description 不要写成“这是一个用于代码审查的技能”而要写成“当用户需要审查 Python 代码、检查代码规范、发现潜在 bug 时使用此技能”。前者是自我介绍后者是使用说明路由效果差别很大。3.2 指令正文的结构化写法指令正文是 skill 的核心我建议用 Markdown 写分成几个固定小节目标、输入、步骤、输出格式、示例、边界情况。目标用一句话说明这个技能要达成什么。输入说明需要用户提供什么信息如果缺失该怎么追问。步骤是最关键的部分要写成有序列表每一步都具体到可执行。输出格式要明确是 JSON、Markdown 表格还是纯文本。如果下游有程序解析格式必须严格定义包括字段名、类型、是否必填。示例部分给出一到两个完整的输入输出对让模型有参照。边界情况列出这个技能不适用的情况以及遇到时该怎么处理。很多人不写边界情况结果模型在遇到异常输入时自由发挥输出不可控。我自己的习惯是在步骤里加入“检查点”比如“完成第三步后确认输出中是否包含所有必填字段如果缺失则回到第二步补充”。这种自我校验的指令能显著降低错误率尤其是多步骤任务。实测下来加了检查点的技能输出合格率能从七成提升到九成以上。3.3 资源引用的组织方式资源引用通常包括工具定义和静态文件。工具定义描述这个技能可以调用哪些外部函数比如搜索、计算、读写文件。每个工具要写清楚名称、参数、返回值。静态文件包括模板、示例数据、参考文档放在技能目录下的resources文件夹里在指令正文中用相对路径引用。这里有一个容易踩的坑工具的参数描述要足够详细否则模型会传错类型。比如一个日期参数要写明格式是YYYY-MM-DD而不是只说“日期”。我见过因为参数描述模糊导致模型传了“明天”这种自然语言工具直接报错。另外静态文件不要太大单个文件建议不超过 100KB否则加载时会占用过多上下文。3.4 技能包的目录结构一个可发布的 skill 包目录结构建议如下my-skill/ ├── skill.yaml # 元数据 ├── instructions.md # 指令正文 ├── resources/ │ ├── template.md # 输出模板 │ └── examples.json # 示例数据 └── tools/ └── definitions.yaml # 工具定义这个结构清晰便于版本管理和分发。skill.yaml 是入口instructions.md 是主体resources 和 tools 是辅助。打包时整个目录压缩成一个文件安装时解压到指定目录即可。热搜词里有人问“skills安装包下载”其实指的就是这种打包好的技能包。4. 实操过程从零写一个可用的 skill4.1 确定技能边界动手之前先想清楚这个技能要解决什么问题边界在哪里。不要写一个“万能助手”技能那等于什么都没写。好的技能边界是一个具体任务有明确的输入和输出执行步骤在十步以内。比如“把一段中文技术文档翻译成英文并保持 Markdown 格式”就是一个好边界“帮我处理文档”就是坏边界。我通常会用一句话测试边界是否清晰如果我不能在三十秒内说清楚这个技能什么时候用、什么时候不用那就说明边界还太模糊。模糊的技能会导致路由混乱主 Agent 不知道该不该加载它最后要么该用的时候没用要么不该用的时候乱用。4.2 编写元数据和指令确定边界后先写元数据。name 用英文description 用中英文各写一遍triggers 列出至少五个典型输入。然后写指令正文按照目标、输入、步骤、输出格式、示例、边界情况的顺序。步骤要写得像给一个新同事的交接文档假设对方很聪明但完全不了解你的业务。写完后自己读一遍问三个问题第一步是否足够具体中间步骤是否有检查点输出格式是否可验证如果任何一个答案是否定的回去改。我一般会改三遍以上第一遍写逻辑第二遍补细节第三遍删冗余。删冗余很重要指令越长模型越容易忽略后面的内容。4.3 本地测试与迭代写完后不要直接发布先在本地测试。测试方法是构造十个典型输入包括正常输入、边界输入和异常输入看输出是否符合预期。正常输入检验基本功能边界输入检验鲁棒性异常输入检验错误处理。每次测试记录输出对比预期找出偏差。迭代时优先改指令正文而不是改元数据。因为元数据影响的是路由指令影响的是执行。如果路由对了但执行错了改指令如果路由错了改元数据。我见过有人执行出错就去改 triggers结果越改越乱。定位问题要看是“没被调用”还是“调用了但做错了”这两个问题的解法完全不同。4.4 发布与版本管理测试通过后给技能打上版本号比如1.0.0。版本号遵循语义化版本规范主版本号变更是因为不兼容的修改次版本号变更是因为新增功能修订号变更是因为修复 bug。发布时把整个目录打包附上变更日志。变更日志要写清楚改了什么、为什么改、影响范围。团队协作时建议把技能包放在 Git 仓库里管理每个技能一个目录用分支做开发用标签做发布。这样任何人想用某个技能直接 checkout 对应标签即可。热搜词里有人问“skills下载平台有哪些”其实最可靠的方式就是团队自建一个 Git 仓库内部技能内部管理比去外部平台找更安全也更贴合业务。5. 常见问题与排查技巧实录5.1 技能不被调用怎么办这是最常见的问题。表现是用户明明说了触发词但主 Agent 没有加载对应技能。排查顺序如下先看元数据里的 triggers 是否包含用户说的原话如果不包含加上再看 description 是否太抽象如果是改具体最后看主 Agent 的系统提示里是否给了技能路由足够的优先级如果没有调整路由指令。我遇到过一次用户说“帮我审一下这段代码”triggers 里写的是“代码审查”结果没匹配上。后来把“审一下”“看看代码”“检查代码”都加进去问题解决。所以 triggers 要尽量覆盖口语化表达不要只写书面语。5.2 技能被调用了但输出不对如果路由正确但输出不符合预期问题通常出在指令正文。排查顺序先看步骤是否足够具体如果某一步是“处理数据”那太模糊要改成“读取 CSV 文件按日期列排序计算每日均值”再看输出格式是否明确定义如果没有加上最后看是否有检查点如果没有在关键步骤后加自我校验。还有一种情况是模型能力不足。有些技能需要较强的推理能力如果底层模型较弱即使指令写得再好也执行不了。这时候要么换更强的模型要么把技能拆得更细降低单步复杂度。5.3 多个技能冲突怎么办当两个技能的 triggers 有重叠时主 Agent 可能不知道该加载哪个。解决方法是给技能加优先级字段或者在 description 里写清楚适用场景的差异。比如一个“代码审查”技能和一个“代码重构”技能triggers 都包含“改代码”那就需要在 description 里区分前者用于发现问题后者用于实施修改。更彻底的做法是合并技能把两个技能合成一个在指令正文里用条件分支处理不同场景。但合并会让技能变复杂所以只在冲突频繁发生时才这么做。我的一般原则是宁可技能多一点、每个简单一点也不要一个大技能包打天下。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能不被调用triggers 不匹配检查用户输入与 triggers 的重合度补充口语化触发词技能不被调用description 太抽象读一遍 description 能否判断使用时机改成具体场景描述输出格式错误输出格式未定义检查指令正文是否有格式说明增加格式定义和示例输出内容遗漏步骤太模糊逐步检查是否每步都可执行细化步骤加检查点多技能冲突triggers 重叠列出重叠技能对比适用场景加优先级或合并技能加载后无响应资源文件过大检查 resources 目录文件大小压缩或拆分文件注意排查时不要同时改多个地方一次只改一个变量改完立即测试。否则你无法判断是哪个改动起了作用。6. 进阶技巧让 skills 真正产生复利6.1 技能组合与编排单个技能解决单点问题多个技能组合起来才能解决复杂任务。组合的方式有两种串行和并行。串行是前一个技能的输出作为后一个技能的输入比如“数据清洗”技能输出干净数据“数据分析”技能接收后生成报告。并行是多个技能同时执行最后汇总结果比如“竞品分析”技能同时调用“搜索”“摘要”“对比”三个子技能。编排的关键是定义清楚技能之间的接口。输出格式要严格字段名要一致否则下游技能解析不了。我通常会在技能包里加一个interface.yaml声明这个技能接收什么、输出什么方便编排时做类型检查。6.2 技能的市场化与复用当团队积累了一定数量的技能后可以建一个内部技能市场让每个人都能搜索、安装、评价技能。市场化的好处是避免重复造轮子一个人写好的技能全团队都能用。评价机制能筛选出高质量技能低质量技能自然被淘汰。市场化要注意权限管理。有些技能涉及敏感数据或内部流程不能对所有人生效。建议给技能加访问控制标签比如public、team-only、private安装时校验权限。热搜词里有人问“skills推荐”其实最好的推荐来自团队内部的使用数据哪个技能被安装最多、评价最高就是最好的推荐。6.3 技能的可观测性技能上线后要能观测运行情况包括调用次数、成功率、平均耗时、错误分布。这些数据能帮你判断哪个技能需要优化。调用次数高但成功率低的技能优先优化调用次数低但成功率高的技能可能是 triggers 没写好需要推广。我一般会在技能包里加一个轻量的日志埋点记录每次调用的输入摘要、输出摘要、耗时、是否成功。日志不要记录完整输入输出避免隐私问题只记录哈希值和长度即可。这些数据汇总后能画出技能的健康度仪表盘一眼看出问题所在。6.4 从 skills 到 Agent 能力体系单个技能是点技能组合是线能力体系是面。当技能数量超过二十个时就需要考虑分类和分层。我通常按业务域分类比如“研发效能”“数据分析”“客户支持”每个域下再按任务类型分层。这样主 Agent 路由时可以先选域再选技能降低路由复杂度。能力体系的最终形态是主 Agent 只负责理解用户意图和路由具体执行全部下沉到技能层。主 Agent 的系统提示可以控制在几百字以内技能包各自独立迭代。这种架构的可维护性远高于单体提示词也是我认为 skills 这个概念最有价值的地方。7. 我踩过的坑与最后分享最早接触 skills 时我把它当成提示词模板来写结果发现路由总是不准。后来才明白skills 的核心不是“写得多好”而是“被找到”和“被正确执行”这两件事。元数据决定被找到指令正文决定被正确执行两者缺一不可。很多人只重视指令正文忽略元数据最后技能写得再好也没人用。另一个坑是过度设计。我一开始想写一个“全能技能”把所有可能的情况都覆盖进去结果指令正文写了三千字模型反而抓不住重点。后来拆成五个小技能每个三百字效果反而更好。技能要像 Unix 工具每个只做一件事做好一件事然后通过组合解决复杂问题。最后分享一个小技巧写技能时把模型当成一个聪明但完全不了解你业务的新人。你不会跟新人说“处理一下数据”你会说“打开这个 CSV按日期排序算每天的平均值输出成表格”。技能指令也要写到这个粒度。我试过把同一份逻辑分别写成“粗粒度”和“细粒度”两个版本细粒度版本的输出合格率高出四成。这个投入是值得的因为技能写一次后面会被调用无数次。