1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题加上项目正文和关键词都是空的我脑子里冒出来的第一个念头是这词太泛了。但结合热搜词里反复出现的 Agent Skills、Claude Agent Skills、Codex Skills、Genkit、GKE 这些词方向其实很明确——这里说的 skills指的是给 AI Agent 挂载的能力模块也就是让一个通用大模型在特定任务上会干活的那套可插拔技能包。你可以把它理解成给一个刚入职的聪明实习生配工具箱。模型本身很聪明但它不知道你公司的代码规范、不知道你项目的目录结构、不知道你写论文要用的引用格式。skills 就是把这些隐性知识和标准操作流程打包成一个个独立模块Agent 需要的时候自己加载用完就放下。这和传统的写一大段 system prompt有本质区别prompt 是常驻的、臃肿的、互相干扰的skills 是按需加载的、隔离的、可复用的。我接触这套东西的契机很实际。之前用 Agent 做代码审查每次都要在对话开头粘贴一大段你要检查命名规范、检查边界条件、检查错误处理……粘到第十次我就烦了。后来发现可以把这套检查逻辑写成一个 skillAgent 检测到审查代码这个意图时自动调用输出格式还统一。这就是 skills 的核心价值把重复的指令沉淀成可调用的能力。这篇文章适合三类人看。第一类是刚听说 Agent Skills、想搞清楚它和普通 prompt 有什么区别的开发者第二类是已经在用 Claude、Codex 这类工具想把自己的工作流沉淀成 skill 的进阶用户第三类是团队里负责搭建 AI 工作流、需要做技能库管理和分发的技术负责人。我会从概念拆解讲到目录结构、从编写技巧讲到测试方法尽量把踩过的坑都摊开说。需要先说明一点skills 这个概念目前在不同平台上的实现细节不完全一样Claude 的 Agent Skills、Codex 的 skills、以及基于 Genkit 自己搭的 skill 系统在文件格式和加载机制上各有差异。但底层的设计哲学是相通的我会以最通用的那套逻辑为主线遇到平台差异的地方单独标注。2. 拆开一个 skill 看内部目录结构决定它能不能被正确加载2.1 一个标准 skill 的最小构成很多人第一次写 skill 失败不是逻辑写错了而是目录结构不对导致 Agent 根本没识别到。这是最冤的一种失败。我见过有人把 skill 写成一个孤零零的 markdown 文件丢在项目根目录然后纳闷为什么 Agent 不调用它。一个能被正确加载的 skill通常是一个独立目录里面至少包含一个入口描述文件。以目前主流的约定来看结构大致是这样my-skill/ ├── SKILL.md # 入口文件包含元信息和主指令 ├── scripts/ # 可选放可执行脚本 │ └── helper.py ├── references/ # 可选放参考资料 │ └── style-guide.md └── assets/ # 可选放模板、示例文件 └── template.txt关键在于SKILL.md这个入口文件。它通常由两部分组成头部是 YAML 格式的元信息frontmatter下面是 markdown 格式的正文指令。元信息里最重要的两个字段是name和description。--- name: code-review description: 审查代码时使用。检查命名规范、边界条件、错误处理、性能隐患并输出结构化审查报告。当用户要求审查代码、review PR、检查代码质量时触发。 ---这里有个新手最容易忽略的点description 不是写给人看的简介而是写给 Agent 看的触发条件。Agent 在决定要不要加载某个 skill 时主要就是读这段描述。所以描述里必须包含什么时候用这个信息而不是只写这是一个代码审查工具。我踩过的坑早期我写的 description 是代码审查技能结果 Agent 十次里有八次不调用它因为它判断不出当前场景该不该用。改成当用户要求审查代码、检查 PR、评估代码质量时使用之后命中率立刻上来了。description 要写成触发条件的清单而不是功能的名词解释。2.2 为什么是目录而不是单文件有人会问既然核心就是 SKILL.md为什么不干脆用一个文件搞定非要搞个目录原因是渐进式加载。Agent 的上下文窗口是有限资源不可能把所有 skill 的完整内容都塞进去。目录结构支持一种分层加载策略Agent 先只读所有 skill 的元信息name description这部分很轻量当判断某个 skill 相关时才去读它的完整正文如果正文里引用了 references 目录下的文件再按需读取。这个机制的好处是你可以挂载几十个 skill但实际消耗的上下文只和当前任务相关的那几个有关。我实测过一个项目挂了 20 多个 skill日常对话的上下文占用并没有明显膨胀就是因为大部分 skill 只贡献了几十 token 的元信息。注意不同平台对目录名的要求不一样。有的要求目录名必须和 name 字段一致有的允许不一致但推荐一致。为了少踩坑建议目录名、name 字段、description 里提到的名字三者保持一致全用小写加连字符。2.3 元信息字段的取舍除了 name 和 description元信息里还能放别的字段但我的建议是能少则少。常见的可选字段包括版本号、作者、依赖项、允许使用的工具列表等。这些字段在团队协作和分发场景下有用但个人使用时加了反而增加维护负担。有一个字段值得单独说允许调用的工具范围。有些平台支持在 skill 里声明这个 skill 只允许读文件不允许写文件这是一种安全约束。如果你写的 skill 涉及执行脚本强烈建议加上这个限制避免 Agent 在你不希望它动手的时候动了手。我在一个自动整理文件的 skill 里就吃过亏——没限制工具范围结果它顺手把几个临时文件也删了虽然不致命但吓出一身冷汗。3. 写 skill 正文的实战心法把隐性经验翻译成可执行指令3.1 正文不是文档是操作手册这是我最想强调的一点。很多人写 skill 正文时习惯性地写成这个技能是用来做 XX 的它有以下特点……这种说明文风格。这是错的。skill 正文应该写成给一个聪明但完全不了解你业务的新人看的操作手册。对比一下两种写法说明文风格错误本技能用于生成周报。周报需要包含本周完成事项、下周计划、风险点三个部分。格式要清晰。操作手册风格正确生成周报时按以下步骤执行先读取本周的 git log提取所有 commit message按 feat / fix / refactor 分类归并同一模块的改动合并成一条输出三个部分本周完成按模块分组、下周计划从 TODO 注释里提取、风险点从 commit 里含 blocked 或 hack 的条目提取每部分用二级标题条目用无序列表不要写客套话看出区别了吗操作手册风格给出了具体的输入来源、处理步骤、输出格式Agent 拿到就能执行。说明文风格只给了目标具体怎么做全靠 Agent 猜结果每次输出都不一样。3.2 用触发条件 执行步骤 输出规范三段式我总结出一个比较稳的正文结构分三段第一段触发条件。明确写清楚什么情况下用这个 skill什么情况下不用。比如当用户明确要求生成周报时使用如果用户只是问这周干了啥属于闲聊不要触发。第二段执行步骤。用有序列表把步骤拆开每步说清楚输入是什么、操作是什么、输出是什么。步骤要细到读哪个文件用什么命令怎么判断这个粒度。第三段输出规范。规定输出的格式、长度、语气。比如输出不超过 500 字不要用 emoji代码块要标注语言。这个结构的好处是可测试。你可以拿几个典型输入去跑看 Agent 是不是按步骤走的、输出是不是符合规范。如果不符合你就知道是哪一段写得不够明确针对性修改。3.3 处理边界情况才是 skill 的价值所在通用模型能处理 80% 的常规情况skill 的真正价值在于把那 20% 的边界情况固化下来。所以正文里一定要写清楚异常怎么处理。举个例子我写过一个根据 commit 生成 changelog的 skill。常规情况很简单但边界情况一堆commit message 不规范怎么办同一天有多个版本发布怎么办有 revert commit 怎么办这些如果不在 skill 里写清楚Agent 每次的处理方式都不一样。我的做法是在执行步骤后面加一段异常处理如果 commit message 不符合规范格式跳过该条并在输出末尾用引用块标注以下 commit 未纳入xxx如果检测到 revert commit找到它 revert 的那条原始 commit两条一起从 changelog 里移除如果同一天有多个 tag按 tag 时间倒序分别生成这些规则写进去之后输出的稳定性提升非常明显。边界处理写得越细skill 的可靠性越高。3.4 控制篇幅正文别超过必要长度有个反直觉的经验skill 正文不是越长越好。我一开始恨不得把所有相关知识都塞进去结果发现正文太长会导致两个问题一是 Agent 读到后面忘了前面二是维护起来痛苦改一处要通读全文。现在的做法是正文只放每次都要用到的核心流程把偶尔才查的参考资料放到 references 目录。比如写一个生成 API 文档的 skill正文里只写生成流程和格式规范把我们团队的 API 命名约定大全这种长文档放到 references 里正文里用一句话引用命名规范详见 references/naming-convention.md。这样正文能控制在几百字以内Agent 读起来轻松我维护起来也轻松。需要更新命名规范时只改 references 文件不用动主流程。4. 让 skill 真正被调用触发机制与调试方法4.1 为什么你的 skill 明明写了却不触发这是被问得最多的问题。skill 写好了Agent 就是不调用怎么办我排查下来原因基本集中在三类第一类description 写得太抽象。前面说过description 是触发依据。如果写的是帮助处理数据Agent 根本不知道什么时候该用。要写成当用户提供 CSV 文件并要求清洗、去重、格式转换时使用。第二类触发词和用户实际说法对不上。你写的是生成周报用户说的是帮我总结下这周的工作语义相近但字面不同。解决办法是在 description 里把常见说法都列上用或连接。第三类skill 之间有冲突。如果你挂了两个 skilldescription 覆盖的场景有重叠Agent 可能选错或者干脆不选。这时候要明确划分边界在各自的 description 里写清楚什么情况下用我什么情况下用另一个。我做过一个对比测试同一个 skilldescription 从数据处理工具改成当用户要求对表格数据去重、筛选、格式转换时使用不适用于数据可视化触发率从大概三成提升到九成以上。description 的精确度直接决定触发率。4.2 用反向测试验证触发边界光测该触发的时候触发了吗不够还要测不该触发的时候触发了吗。这叫反向测试。具体做法是准备一组不应该触发该 skill 的输入跑一遍看 Agent 会不会误触发。比如你的 skill 是生成周报那帮我看看这个 bug 怎么修就不该触发它。如果误触发了说明 description 的边界没划清楚需要加上排除条件。我一般会准备 5 个正向用例和 5 个反向用例每次改完 skill 都跑一遍。这个习惯帮我避免了好几次改了一处、坏了一片的情况。4.3 调试时把中间过程打出来Agent 调用 skill 的过程有时候是黑盒你不知道它到底读没读、读到哪一步。我的做法是在 skill 正文里加一些可观测的中间输出。比如在关键步骤后加一句在此步骤输出当前处理进度格式为 [步骤 N/总步骤数]。这样跑的时候你能看到它走到哪了卡在哪一步一目了然。调试完再把这句话删掉避免正式使用时输出太啰嗦。另一个技巧是故意制造一个错误输入看 skill 的异常处理分支有没有被正确执行。比如给一个格式完全不对的文件看它是不是按你写的规则跳过了而不是硬着头皮瞎处理。5. 团队场景下的 skill 管理从个人玩具到协作资产5.1 版本控制与命名规范个人用 skill 怎么命名都行但一旦进入团队协作命名规范就是刚需。我们团队踩过的坑两个人分别写了format-code和code-format两个 skill功能几乎一样Agent 加载时经常二选一输出风格还不统一。后来定了一套规范领域前缀 动作 对象全小写连字符。比如frontend-format-component、backend-review-api、docs-generate-changelog。前缀按领域分避免跨领域重名动作在前对象在后方便按动作检索。版本控制方面skill 目录直接进 git 仓库和代码一起管理。每次修改 skill 都走 PR 流程至少一个人 review。这听起来有点重但 skill 是会直接影响 Agent 行为的改错了影响面比改一行代码还大。5.2 共享 skill 库的组织方式当 skill 数量超过十几个就需要考虑怎么组织了。我们试过两种方案方案一单仓库集中管理。所有 skill 放一个仓库按领域分目录。好处是查找方便、统一维护坏处是仓库会越来越大而且不同领域的 skill 更新频率不一样容易互相干扰。方案二按领域拆多个仓库。每个领域一个仓库各自维护。好处是解耦坏处是跨领域引用麻烦而且新人不知道一共有哪些 skill。最后我们采用的是混合方案核心通用 skill比如代码审查、文档生成放主仓库领域专属 skill 放各自的业务仓库主仓库里维护一个索引文件列出所有 skill 的位置和用途。这样既保证了通用 skill 的统一又给了业务团队灵活性。5.3 skill 的复用与组合skill 之间可以互相引用这是提升复用率的关键。比如我写了一个git-analyze-commits的 skill 专门负责解析 commit 历史然后generate-changelog和generate-weekly-report两个 skill 都引用它不用各自重复实现解析逻辑。组合的方式有两种一种是在正文里显式引用写调用 git-analyze-commits 获取结构化 commit 数据另一种是通过 references 共享文档多个 skill 引用同一份规范文档。我倾向于第一种因为显式引用让依赖关系清晰改一个 skill 能立刻知道影响哪些下游。但要注意别搞成循环依赖A 引用 B、B 又引用 AAgent 会陷入死循环。我们现在的规矩是 skill 引用关系必须是单向的且层级不超过三层。6. 几个真实场景的 skill 拆解6.1 代码审查 skill从泛泛而谈到逐项检查我最早写的代码审查 skill 很水正文就一句审查代码质量指出问题。结果 Agent 每次输出的都是建议增加注释注意边界条件这种正确的废话。后来重写成逐项检查清单命名检查变量名是否用了无意义缩写如tmp、data1函数名是否是动词开头边界检查数组访问是否有越界可能除法是否有除零保护空值是否有判空错误处理所有可能失败的操作是否有 try-catch 或错误返回错误信息是否包含上下文性能隐患循环内是否有重复计算是否有 N1 查询大对象是否频繁拷贝输出格式每个问题标注严重程度高/中/低、所在行号、修改建议改完之后审查报告的质量完全不一样了能直接拿去当 PR 评论用。关键就是把审查什么从抽象概念变成具体清单。6.2 论文写作 skill格式规范的固化帮人写论文时最烦的是格式。不同期刊要求不一样参考文献格式、图表编号、摘要字数都有讲究。这些规则写进 skill 之后Agent 生成的内容直接就是符合格式的省去大量返工。这个 skill 的正文重点是把格式规则写成可执行的检查项。比如参考文献部分不是写按 APA 格式而是写作者姓在前名缩写在后年份用括号期刊名斜体卷号加粗页码用 en dash 连接。越具体Agent 执行得越准。6.3 分镜脚本 skill创意类任务怎么固化创意类任务能不能用 skill能但思路不一样。创意任务不能把输出写死否则就失去创意了。我的做法是固化结构和约束放开内容。比如分镜脚本 skill正文规定的是每个镜头必须包含镜号、景别、画面描述、台词、时长五个字段景别只能从远全中近特里选总时长控制在 30 秒到 3 分钟之间。至于具体画面是什么交给 Agent 发挥。这样既保证了脚本的规范性又保留了创意空间。7. 关于 skill 开发我踩过的那些坑7.1 把 skill 当成 prompt 的堆砌刚开始我以为 skill 就是把以前写的长 prompt 拆成几个文件。结果发现完全不是一回事。prompt 是一次性对话的上下文skill 是可复用的能力单元。前者可以随意、口语化后者必须结构化、可测试。用写 prompt 的思路写 skill写出来的东西没法复用换个场景就失效。7.2 忽略加载顺序和优先级当多个 skill 同时可能被触发时加载顺序会影响结果。我遇到过两个 skill 都涉及格式化输出一个要求用表格一个要求用列表Agent 随机选了一个输出风格不稳定。后来在 description 里明确了优先级当同时满足多个 skill 触发条件时优先使用本 skill问题才解决。7.3 没有做输入校验skill 假设输入是某种格式但用户实际给的可能是另一种。我写过一个解析日志文件的 skill假设日志是标准格式结果用户给了一个格式混乱的文件Agent 硬解析出一堆垃圾。后来在正文开头加了输入校验步骤先检查文件是否符合预期格式不符合则提示用户并终止不要尝试解析。7.4 更新 skill 后没有回归测试改了一个 skill 的某个步骤结果影响了依赖它的其他 skill。这个坑我踩过两次后来养成了习惯任何 skill 修改后跑一遍所有依赖它的 skill 的测试用例。依赖关系在主仓库的索引文件里维护改之前先查一下谁依赖我。8. 从今天开始搭建你的第一个 skill如果你读到这里还没动手我给一个最小可执行的起步方案。先选一个你每周至少重复三次的任务。重复频率高说明它值得被固化频率太低投入产出比不划算。比如整理会议纪要生成日报格式化 JSON这类。然后按这个顺序写建目录目录名用任务名的小写连字符形式写 SKILL.md 的元信息description 里把触发条件写清楚正文按触发条件 执行步骤 输出规范 异常处理四段写准备三个正向用例和一个反向用例跑一遍根据结果调整 description 和步骤描述第一版不用追求完美能跑通就行。用上一周把遇到的问题记下来周末统一改一版。迭代两三轮之后你会发现这个 skill 已经成了你工作流里离不开的一环。我个人最大的体会是skill 的价值不在于写得多复杂而在于把一件小事做到每次结果都一致。一个只做一件小事的 skill只要稳定就比一个功能强大但输出飘忽的 skill 有用得多。从最小的那个任务开始先让它稳再让它强。