Agent Skill 开发指南：从零打造可复用工作流

1. 从“每次都要重新讲一遍”说起Skill 到底解决什么问题我最早接触 Agent 工作流的时候犯过一个很典型的错误把所有操作流程都塞进对话里。每次让 Agent 帮我处理一个固定任务比如“把一份会议纪要整理成结构化周报”我都要重新描述一遍格式要求、字段顺序、语气风格、哪些内容要合并、哪些要单独列出。一次两次还行到了第十次我开始烦了——不是烦 Agent是烦我自己。后来我意识到这不是 Agent 不够聪明而是我没有把“我已经想清楚的流程”沉淀下来。Skill 的核心价值就是把那些你反复讲、反复调、反复修正的操作流程变成一份可复用、可触发、可版本管理的结构化文件。你写一次之后 Agent 在合适的场景下自动加载不需要你每次从头交代。这件事听起来简单但真正动手做的时候很多人会卡在几个地方Skill 文件到底长什么样description 怎么写才能被正确触发流程步骤要细到什么程度哪些内容该写进 Skill哪些不该我前后折腾了十几个 Skill踩了不少坑也总结出一套比较稳的做法。这篇文章就围绕skill-creator这个思路把“如何打造自己的专属 Skill”这件事讲透。先明确一下适用人群如果你已经在用 Agent 处理重复性任务比如代码审查、文档整理、数据分析、内容生成、项目初始化那 Skill 对你价值最大。如果你还没开始用 Agent也没关系理解 Skill 的设计思路对你梳理任何“可复用流程”都有帮助。提示Skill 不是提示词模板的简单堆砌。它更像一份“操作手册 触发条件 边界说明”的组合体写得好不好直接决定 Agent 能不能在正确的时候做正确的事。2. Skill 文件的骨架SKILL.md 里到底该放什么2.1 为什么是 Markdown 而不是 JSON 或 YAML我试过用 JSON 写 Skill也试过 YAML最后回到 Markdown。原因很实际Skill 的主体内容是“给人看也给模型看”的自然语言流程描述Markdown 在可读性和结构表达上最平衡。JSON 适合机器解析但你写流程的时候会不断被引号、转义、层级括号打断思路YAML 好一点但长文本段落写起来还是别扭。Markdown 的标题层级、列表、代码块、引用块刚好能覆盖 Skill 需要的所有表达形式。另一个原因是Agent 在读取 Skill 时本质上是在做“上下文注入”。Markdown 的标题结构能帮助模型快速定位到“这个 Skill 是干什么的”“什么时候用”“具体步骤是什么”比纯结构化数据更符合模型的阅读习惯。2.2 一个 Skill 的最小可用结构我不建议一上来就追求大而全。先跑通一个最小闭环再逐步加细节。下面是我常用的最小结构--- name: weekly-report-builder description: 将会议纪要或零散工作记录整理成结构化周报适用于需要按固定模板输出周报的场景。 --- ## 触发条件 当用户提到“周报”“weekly report”“整理本周工作”等关键词且提供了原始记录时加载本 Skill。 ## 输出格式 1. 本周完成事项按项目分组 2. 进行中事项标注当前进度 3. 风险与阻塞标注影响范围 4. 下周计划按优先级排序 ## 处理规则 - 合并重复事项保留最新状态 - 未明确归属的事项放入“其他” - 风险项必须标注影响范围无法判断时标注“待确认”这个结构里name和description放在 front matter 里是为了让 Agent 在“决定是否加载这个 Skill”时有一个快速判断依据。正文部分则分成触发条件、输出格式、处理规则三块分别回答“什么时候用”“产出什么”“怎么处理细节”。2.3 description 的写法决定 Skill 能不能被触发这是我最想强调的一点。很多人 Skill 写得很认真但 description 写得太泛导致 Agent 根本不知道什么时候该用它。比如你写“帮助处理文档”这等于没写。Agent 面对几十个 Skill 的时候只能靠 description 做初筛写得太泛就会被忽略或者被错误触发。我的经验是description 要包含三个要素动作 对象 场景。举个例子差帮助整理内容好将会议纪要、聊天记录等非结构化文本整理成按项目分组的周报适用于需要固定模板输出的周报场景再比如一个代码审查 Skill差审查代码好对 Python 代码进行静态审查检查命名规范、异常处理、边界条件适用于提交前的自查场景你会发现好的 description 里其实隐含了“触发词”。Agent 在匹配时会看用户输入里有没有“周报”“会议纪要”“Python 代码审查”这类信号。你 description 里写清楚了匹配成功率就高。注意description 不要写得太长控制在两三句话以内。太长反而会稀释关键信息模型抓不住重点。2.4 触发条件要不要单独写要。而且我建议写得比 description 更具体。description 是给 Agent 做初筛用的触发条件是给 Agent 做二次确认用的。比如## 触发条件 满足以下任意一条时加载 - 用户明确提到“周报”或“weekly report” - 用户提供了会议纪要、工作记录等原始材料并要求“整理成固定格式” - 用户说“按上周的模板来” 以下情况不加载 - 用户只是问“周报怎么写”但没有提供原始材料 - 用户要求的是日报或月报把“不加载”的情况也写出来能有效减少误触发。我一开始没写这部分结果 Agent 在我只是讨论“周报格式”的时候也把 Skill 加载了反而干扰了正常对话。3. 把流程写细从“能跑”到“稳定跑”的关键差距3.1 步骤粒度写到“不需要再问”为止Skill 最容易出问题的地方是步骤写得太粗。比如你写“整理会议纪要”Agent 会问你要不要合并同一议题的多次讨论要不要保留发言人时间戳要不要你每回答一次就等于在补全 Skill。正确的做法是把你曾经回答过的所有问题提前写进 Skill 里。我现在的判断标准是如果一个步骤在执行时我还需要额外解释才能让 Agent 做对那这个步骤就没写够。比如“整理会议纪要”这个 Skill我会写到这个程度## 处理规则 ### 议题合并 - 同一议题的多次讨论合并为一个条目 - 合并时保留最新结论历史讨论放入“讨论过程”子项 - 如果多次讨论结论冲突标注“存在分歧”并列出各方观点 ### 发言人处理 - 默认保留发言人姓名 - 如果用户要求匿名用“发言人A/B/C”替代 - 如果发言人未明确标注“未标注” ### 时间戳处理 - 默认不保留时间戳 - 如果用户要求保留格式统一为 HH:MM - 跨天会议标注日期这些规则不是我凭空想的是我在实际使用中一次次被问出来的。每被问一次我就补一条。补到后来Agent 基本不再追问直接出结果。3.2 边界条件什么不做比做什么更重要Skill 写多了会发现明确“不做什么”往往比“做什么”更能提升稳定性。因为 Agent 的默认行为是“尽量帮忙”你不设边界它就会自由发挥。比如一个“代码审查”Skill如果不写边界Agent 可能会顺手帮你重构代码、改命名、甚至调整架构。这些不一定是坏事但会偏离你原本的意图。我会在 Skill 里专门加一节“边界与禁止事项”## 边界与禁止事项 - 只做审查不直接修改代码 - 不评价代码风格偏好如空格 vs 制表符除非用户明确要求 - 不检查业务逻辑正确性只检查通用规范 - 如果发现严重问题标注“需人工确认”不自行判断这几条写进去之后Agent 的输出范围就收窄了我拿到结果后不需要再过滤一遍。3.3 输出格式给模板不给描述“输出一个结构化的报告”——这种描述等于没描述。Agent 对“结构化”的理解和你可能完全不一样。正确做法是直接给模板用占位符标出需要填充的部分。## 输出格式 ### 本周完成 - [项目名][事项描述][状态] ### 进行中 - [项目名][事项描述]进度[百分比或阶段] ### 风险与阻塞 - [风险描述]影响[影响范围]建议[建议动作] ### 下周计划 - [优先级] [事项描述]有了这个模板Agent 的输出会非常稳定。我甚至会把模板放在 Skill 的最前面让 Agent 先看到“最终要产出什么”再去看处理规则这样它处理细节时更有目标感。3.4 示例给一个完整输入输出对如果 Skill 的逻辑比较复杂我会在最后附一个完整的输入输出示例。这相当于给 Agent 一个“参考答案”能显著提升首次执行的准确率。## 示例 输入 “周一跟产品对了需求确认要做导出功能周三开发说导出性能有问题需要加缓存周五测试提了三个bug两个已修一个待确认。” 输出 ### 本周完成 - 导出功能与产品确认需求已完成 ### 进行中 - 导出功能性能优化加缓存方案进度开发中 - 导出功能bug修复进度2/31个待确认 ### 风险与阻塞 - 导出性能问题影响上线时间建议优先验证缓存方案 ### 下周计划 - 高完成剩余bug修复 - 中验证缓存方案效果这个示例一放进去Agent 基本就能理解“合并”“标注状态”“风险提取”这些规则具体怎么落地了。4. 触发机制与加载策略让 Skill 在该出现的时候出现4.1 Skill 的触发不是“关键词匹配”那么简单很多人以为 Skill 触发就是看用户输入里有没有某个词。实际用下来Agent 的触发判断更接近“意图匹配”。它会综合看用户当前在做什么任务、上下文里有没有相关信号、当前加载的其他 Skill 有没有冲突。所以你在写 Skill 的时候不能只堆关键词还要把“意图”写清楚。比如“周报”这个词可能出现在“帮我写周报”“周报模板发我”“周报怎么写”三种语境里。前两种应该触发第三种不应该。如果你只写关键词“周报”就会误触发。我的做法是在触发条件里写清楚意图## 触发条件 加载本 Skill 需要同时满足 1. 用户提供了原始工作记录会议纪要、聊天记录、任务列表等 2. 用户要求输出固定格式的周报 仅提到“周报”但没有提供原始记录时不加载。4.2 多个 Skill 冲突时怎么办当你积累到十几个 Skill 之后冲突是必然的。比如你有一个“通用文档整理”Skill又有一个“周报生成”Skill用户输入“把这份记录整理一下”两个都可能被触发。这时候 Agent 会怎么选取决于你的 Skill 里有没有写优先级。我会在 Skill 里加一行## 优先级 当与“通用文档整理”Skill 同时匹配时优先加载本 Skill。或者在 description 里写清楚适用范围description: 将工作记录整理成周报。仅适用于周报场景通用文档整理请使用 document-organizer。这样 Agent 在做选择时就有依据了。4.3 手动触发与自动触发有些 Skill 适合自动触发比如“代码审查”“周报生成”有些适合手动触发比如“项目初始化”“批量重命名”。手动触发的 Skill我会在 description 里写“需用户明确调用”避免 Agent 自作主张。description: 初始化新项目目录结构。需用户明确说“初始化项目”时加载不自动触发。这个区分很重要。自动触发的 Skill 如果误触发会打断正常对话手动触发的 Skill 如果自动触发可能会在你还没准备好时就执行操作。5. 从零到一用 skill-creator 思路搭建你的第一个 Skill5.1 先选一个“你已经做过至少五次”的任务不要一上来就挑战复杂任务。选一个你已经重复做过至少五次、流程已经比较清晰的任务。比如把零散笔记整理成结构化文档对一段代码做提交前自查把英文技术文档翻译成中文并保留术语从一堆数据里提取关键指标并生成摘要选好之后先别急着写 Skill。先手动做一遍把每一步都记下来。记的时候注意哪些步骤是你下意识做的哪些判断是你凭经验做的这些往往是 Skill 里最需要写清楚的部分。5.2 用“三问法”确定 Skill 边界写之前问自己三个问题这个 Skill 的输入是什么是用户的一段话、一个文件、还是多个来源的材料输出是什么是一段文本、一个表格、还是一个文件中间有哪些判断哪些情况需要特殊处理哪些情况应该拒绝这三个问题的答案基本就构成了 Skill 的骨架。输入对应触发条件输出对应输出格式判断对应处理规则。5.3 写第一版不求全求跑通第一版 Skill 不要写太长。我的经验是控制在 50 行以内先把主流程跑通。比如--- name: note-organizer description: 将零散笔记整理成按主题分组的结构化文档适用于会议记录、学习笔记等场景。 --- ## 触发条件 用户提供零散笔记并要求“整理”“归类”“结构化”时加载。 ## 输出格式 ### 主题一 - 要点 - 要点 ### 主题二 - 要点 ## 处理规则 - 按内容相关性分组每组不超过 5 条 - 合并重复要点 - 无法归类的放入“其他”写完第一版拿三个真实案例跑一遍。看哪里卡住、哪里输出不对、哪里需要你额外解释。把这些都记下来作为第二版的补充。5.4 迭代每次只改一个地方Skill 迭代最忌讳一次改太多。你改了三处结果输出变差了你都不知道是哪处改坏了。我的做法是每次只改一个地方改完立刻用之前的案例验证。比如这次只加“合并重复要点”的规则下次只加“每组不超过 5 条”的限制。这样你能清楚知道每条规则的实际效果。我自己的“周报生成”Skill 迭代了七版。第一版只能做简单分组第三版加了风险提取第五版加了优先级排序第七版加了示例。每一版都是被真实问题逼出来的不是提前设计好的。6. 那些没人告诉你但一定会踩的坑6.1 Skill 写太长反而触发不了我一开始觉得 Skill 越详细越好结果写了一个 300 行的 SkillAgent 反而不太愿意加载它。后来才明白Skill 的加载是有上下文成本的。太长会占用大量上下文Agent 在判断是否加载时会犹豫。而且太长的 Skill 里关键信息容易被淹没。我的建议是主 Skill 控制在 100 行以内超出的部分拆成子 Skill 或附录。如果确实需要很长的规则把最核心的触发条件和输出格式放在前面细节规则放在后面并标注“按需查阅”。6.2 description 写得太“聪明”导致匹配失败有些人喜欢在 description 里用很抽象的表达比如“赋能内容生产”“提升工作效率”。这些词对人有用对 Agent 匹配没用。description 要写具体的动作和对象不要写价值主张。“将会议纪要整理成周报”比“提升工作效率”有用一百倍。6.3 忘了写“不触发”的情况这个坑我踩过好几次。只写“什么时候触发”不写“什么时候不触发”结果 Agent 在闲聊时也加载 Skill输出一堆格式化的内容很尴尬。后来我强制自己在每个 Skill 里都加一节“不加载的情况”误触发率明显下降。6.4 输出格式用“描述”而不是“模板”“输出一个清晰的列表”——这种描述 Agent 理解不了。什么叫清晰几条什么格式直接给模板用占位符。这是提升输出稳定性最有效的一招没有之一。6.5 没有版本管理Skill 是会不断迭代的。如果你不记录每次改了什么改到后面你会忘记为什么某条规则存在。我的做法是在 Skill 文件末尾加一个简单的变更记录## 变更记录 - v1.0初始版本支持基本分组 - v1.1增加合并重复要点规则 - v1.2增加风险提取规则 - v1.3增加输出示例不用很正式但要有。这在你回头排查问题时非常有用。7. 进阶让 Skill 之间产生协作7.1 Skill 组合一个任务拆成多个 Skill当你的任务变复杂时单个 Skill 会变得臃肿。这时候可以考虑拆成多个 Skill让它们协作。比如“周报生成”可以拆成meeting-note-parser解析会议纪要提取事项和状态weekly-report-builder把解析结果整理成周报格式risk-extractor从事项中提取风险项每个 Skill 只做一件事组合起来完成完整流程。这样做的好处是每个 Skill 都更短、更稳定也更容易复用。比如risk-extractor也可以用在项目报告、复盘文档等场景。7.2 用 Skill 串联工作流更进一步你可以写一个“工作流 Skill”专门描述多个 Skill 的调用顺序## 工作流 1. 加载 meeting-note-parser解析原始记录 2. 加载 risk-extractor提取风险项 3. 加载 weekly-report-builder生成最终周报 4. 如果风险项超过 3 条额外加载 risk-prioritizer 排序这个工作流 Skill 本身不处理具体内容只负责编排。这样你调整流程时只需要改工作流 Skill不用动各个子 Skill。7.3 Skill 的复用与迁移写好的 Skill 可以跨项目复用。比如“代码审查”Skill在 A 项目写完B 项目直接拿过去用只需要微调触发条件。我现在的做法是维护一个“Skill 库”按领域分类文档处理、代码审查、数据分析、内容生成。新项目开始时先从库里找现成的找不到再写新的。提示跨项目复用 Skill 时注意检查触发条件里有没有项目特定的关键词。比如“检查导出模块”这种换项目就不适用了要改成通用表达。8. 我自己的 Skill 管理习惯最后分享几个我日常管理 Skill 的习惯都是踩坑之后养成的。第一Skill 文件统一命名。我用领域-动作.md的格式比如doc-weekly-report.md、code-review-python.md。这样在目录里一眼就能找到也方便 Agent 按领域筛选。第二每个 Skill 都写“最后验证时间”。在 front matter 里加一行last_verified: 2025-06-01。Skill 放久了可能会因为 Agent 版本更新而失效定期验证一下过期的就更新或删除。第三保留“废弃 Skill”目录。有些 Skill 不用了但里面的规则可能还有参考价值。我会把它们移到deprecated/目录而不是直接删掉。过段时间回头看经常能捡回一些有用的东西。第四用真实案例做回归测试。每次改完 Skill我会拿之前存的三到五个真实案例跑一遍确认输出没有变差。这个习惯帮我避免了好几次“改一处坏三处”的情况。第五Skill 不要写“完美”要写“够用”。我见过有人花两周写一个 Skill结果用了一次就不用了。Skill 的价值在于被使用不在于被写得多漂亮。先写一个能跑的版本用起来再迭代。这才是 skill-creator 这个思路真正的意义——不是创造一个完美的 Skill而是创造一个能持续进化的 Skill。