Agent Skill编写实战：设计思路、目录结构与调试方法

我做 Agent 开发也有一年多了从最初的简单对话机器人做到后面带多工具协作的智能体前后手写了十几个 Skill调试到吐血的经历也不少。我发现很多新手甚至一些有经验的开发者都容易把 Skill 想得太简单——以为就是给 Agent 写一段详细一点的 Prompt结果写出来的东西要么触发不了要么执行流程乱成一锅粥要么输出格式各种不稳定。今天这篇文章就专门讲讲“怎么写一个好用的 Agent Skill”从设计思路、目录结构、描述文件、核心逻辑到测试迭代把我踩过的坑和沉淀下来的方法一次讲透。不管你是想给个人项目写个顺手的小工具还是准备在团队里搭一套规范的 Agent 体系这篇文章应该都有你能直接拿走的东西。1. 先搞清楚Agent Skill 到底是什么1.1 从 Agent 的工作原理说起任何 Agent 系统的核心都可以概括成一句话大模型在一个“思考—行动—观察”的循环里反复决策决定下一步该调什么工具、看什么结果、再做什么调整。这个循环听起来不复杂但一旦任务场景变得稍微复杂一点纯靠模型自由发挥就会出各种幺蛾子模型可能凭空捏造一个不存在的函数可能把本该先做的步骤放到后面可能在同一个输出里一会儿给 JSON 一会儿给 Markdown。Skill 这个机制就是专门来解决这些问题的。可以把它理解成普通 Prompt 是给模型一张“任务描述”而 Skill 是给模型一本“操作手册”加一套“工具箱”。当 Agent 识别到某个特定场景的任务时它不再临时瞎编方案而是按 Skill 里定义好的步骤、工具和边界去执行。这样做带来的直接好处有两个。第一是稳定性大幅提升同样的任务无论用户怎么换着说法提问只要触发了这个 Skill执行路径基本都是固定的。第二是可调试性变强任务失败了你可以很快定位是哪个步骤出了问题而不是看着一大段模型自由发挥的输出发呆。1.2 Skill 和普通 Prompt 的区别我刚开始接触这些概念时也以为 Skill 无非就是长一点的 Prompt。实际做下来发现这俩差别非常大理解不到位的话后面写什么都别扭。第一个差别在可复用性。Prompt 通常是为某一次具体对话或者某一个具体场景服务的换个场景就得重新写。Skill 则是被当作一个独立模块来设计的里面有清晰的输入、输出、工具调用描述可以被 Agent 在匹配到对应场景时动态加载。同一个 Skill 可以今天被这个任务用明天被那个任务用后天换一个完全不同的 Agent 也能用。第二个差别在可控性。纯 Prompt 本质上只是“建议”模型采纳与否全靠自觉。Skill 里声明的工具、参数约束、输出格式在框架层面上会被强制执行。比如你定义了“必须先用 fetch_diff 工具拿到代码 diff然后才能进入分析阶段”那么在执行时框架会要求模型按照这个链路来模型就不能随便跳过或者乱改顺序。这一点对于工程化场景极其重要因为交付的东西必须行为可预期而不是碰运气。第三个差别在维护方式。Prompt 往往散落在聊天记录或者代码里改起来到处找。Skill 有固定的目录结构、版本管理和测试流程改一个地方不会影响其他地方。做项目久了你就知道这个东西带来的长期收益远超想象。1.3 什么样的任务适合用 Skill 封装不是所有任务都需要做成 Skill也不是什么任务都能做好。我的判断标准很简单三条满足一条就可以考虑重复出现的任务值得封装。比如整理会议纪要、生成周报、做代码 review、给文章配摘要这些任务几乎天天出现一次性把 Skill 写好后面就是持续复用性价比很高。流程固定、步骤清晰的任务适合封装。比如“拉取一个仓库的 PR 变更 → 逐文件分析 → 输出问题清单”这个流程每一步都很明确做成 Skill 之后 Agent 执行起来会非常稳。反过来如果任务本身没有固定路径每一步都要靠模型随机发挥那封装出来效果也不会好。需要多个工具串起来才能完成的任务也特别适合用 Skill 来兜底。比如有的任务需要先读取文件、再转换格式、再调用模型做生成涉及多个工具接力如果不封装成 Skill模型在切换工具时很容易丢上下文一旦封装好整条链路就固化了。到这里我想强调一句不要为了封装而封装。我会看到有人把一个简单到不需要工具的任务也硬做成 Skill结果反而是画蛇添足。那些一次性的、高度依赖上下文随机发挥的任务比如闲聊、纯创意发散老老实实用普通对话就好封装 Skill 只会让系统变得臃肿。2. 好 Skill 的设计思路先拆需求再写实现2.1 一切从“目标用户”和“使用场景”开始很多人一上来就写代码这是我最不建议的做法。Skill 写出来是要给用户用的用户是谁、怎么提问、期待得到什么这些问题没想清楚后面全是白搭。我每次写 Skill 之前都会先在文档里回答三个问题这个 Skill 是给谁用的是给普通用户通过聊天窗口自然语言触发的还是给开发者通过 API 或者命令行工具调用的这两类使用方式对手感的要求完全不同。普通用户触发时描述文件里就要多写一些自然口语化的触发场景开发者使用时参数定义和输出结构反而要更严格一些。用户最常输入的请求长什么样这个不能凭空想象最好去翻一翻历史对话记录、用户反馈或者需求文档把这些真实语句摘出来作为后面写描述文件触发条件的素材。比如用户通常会说“帮我 review 一下这个 PR”而不是“执行代码审查工具”。用户期望拿到什么形式的输出是要一段结论性的文字还是要一份结构化报告或者直接要一个 JSON 数据这个直接决定 Skill 输出模板怎么设计。有些场景用户就是要一句话结论你让 Skill 输出一个巨大的 JSON 反而多余。这三个问题想清楚Skill 的骨架基本就出来了。2.2 明确能力边界什么该做什么不该做一个好 Skill 绝对不是什么都会一点的“瑞士军刀”恰恰相反它是能力范围越窄越好用的“专用工具”。我的经验是Skill 范围越小模型越容易准确理解执行成功率越高维护成本也越低。举个例子假设你要做一个“代码审查 Skill”。你当然可以试图让它同时处理语法检查、安全漏洞扫描、依赖包分析、性能诊断、风格检查但那样做几乎注定失败。因为当一堆任务混在一起时模型很容易在“当前到底该执行哪个子任务”“该调用哪个工具”这些决策点上犯迷糊最后每一项都做得不彻底。正确的做法是先聚焦一个核心能力比如“对指定代码 diff 做逐行 review标记 bug 风险、安全问题和可读性问题输出带严重等级的清单”。把这个核心做扎实了后面再考虑要不要扩展其他能力。我在项目里早期就吃过这个亏写过一个“全能文档处理 Skill”号称能总结、翻译、提取表格还能生成报告结果用户每次让它做具体任务时它都先花好大劲在“选哪个功能”上效果可想而知。后来把这个 Skill 拆成三个独立的每个只做一个能力整体准确率肉眼可见地上来了。2.3 把流程拆成可执行步骤设计 Skill 的时候我脑子里一定会把从“用户请求”到“最终输出”的整条链路过一遍。一般来说流程大概是这样的识别触发条件 → 解析输入 → 提取必要参数 → 调用工具 A 获取中间数据 → 检查中间结果是否合法 → 调用工具 B 处理数据 → 汇总结果 → 格式化成输出。拆流程时有一个很重要的原则尽量让每一步都变成“确定性操作”。所谓确定性操作就是同样的输入必然得到同样的输出比如读文件、查接口、跑脚本、算哈希这些都是模型可以依赖的稳定步骤。而那些需要模型发挥理解力、判断力的步骤比如“判断这段代码作者的意图”“评估这个架构的合理性”要尽量往后放放到前面已经拿到足够信息之后再让模型去做判断。这样做的好处是模型在最后做判断时有充分的依据而不是从头就开始瞎猜。这一步是很多人会忽略掉的。他们写 Skill 就写一个巨大的提示词里面夹杂着工具调用但是每个工具的触发条件、每个步骤的输入输出都写得模模糊糊模型自然容易跑偏。2.4 输入输出设计少让模型猜输入参数这块我的建议是设计得越扁平越好嵌套层级不要太多。比如你要让 Agent 读一个文件就传“文件路径”不要传一个包含一系列配置项的对象更不要让模型自己去推断应该传什么。参数的定义要写清楚类型、取值范围、默认值比如“max_results 是可选参数默认 10取值范围 1 到 100”这样模型生成参数的时候不容易出错。输出方面我强烈建议 Skill 尽量输出结构化内容。能输出 JSON 就输出 JSON能输出 Markdown 表格就不要写一段啰嗦的长文本。为什么因为 Agent 的下游处理往往需要解析上一环节的输出如果是纯文本下游很难稳定抽取信息如果是 JSON下游解析就非常可靠。哪怕你的用户只想要一段自然语言结论也建议在输出结构里同时包含一个“结论摘要”字段和一个“详细数据”字段这样既满足了阅读需求又保留了机器可读性。3. 实操从头写一个可用 Skill 的完整过程3.1 目录结构与配置不同框架对 Skill 的目录结构要求不完全一样但大体思路是相通的。以我常用的组织方式为例一个 Skill 的目录结构大致是这样skills/ code-review/ SKILL.md tools/ fetch_diff.sh analyze.py assets/ templates/ review_output.mdSKILL.md 是 Skill 的入口文件框架加载 Skill 时首先读取它。里面核心内容有三块Skill 的名称和一句话简介、触发条件和适用场景描述、执行流程说明。很多框架还支持在 SKILL.md 头部用 YAML 格式的 front matter 声明元信息比如 name、description、参数 schema、需要挂载的工具列表等。关于目录结构的建议能拆文件就拆文件不要把所有的代码、提示词、模板全部堆在一个文件里。我以前图省事把提示词直接写进 SKILL.md结果每次微调都要动整个文件Git 历史也乱得不行。后来学乖了把提示词模板、工具脚本、输出模板各自独立成文件SKILL.md 只负责把它们串起来。这样每次改动的影响范围都清晰可控。3.2 写描述文件这是最容易被低估的部分如果只能挑一个环节决定 Skill 的成败我会毫不犹豫地选描述文件的编写。描述文件的核心作用是让 Agent 在“决定调用哪个 Skill”的决策点做出正确选择。它决定了 Skill 的“曝光率”和“命中率”直接关系到这个 Skill 在真实场景里能不能被用起来。描述里要把三件事讲清楚。第一是触发场景也就是用户说什么样的话、任务属于哪个类别时应该考虑使用这个 Skill。这里千万不要只列几个关键词要写场景。比如你写“当用户需要审查一段代码、review PR、检查代码潜在 bug 时”这个描述就要比简单写“code review”四个字好用得多因为它是用用户的实际语言来描述的模型更容易匹配上。第二是能力边界也就是这个 Skill 能做什么、不能做什么。写清楚边界能有效避免模型在 Skill 能力不足的时候强行拿来用也能避免几个 Skill 之间功能重叠导致的“选择困难”。比如一个 Skill 能“根据代码 diff 做 review”它就不能“重写整个项目代码”这两者要区分清楚。第三是输出承诺也就是用户使用这个 Skill 之后大概会得到什么。写清楚输出形式比如“输出包含问题清单、严重等级、修复建议的 Markdown 报告”模型就知道该往哪个方向组织输出用户的预期也更容易被满足。这里有个实践中的分寸问题描述文件写得太长模型在决策时反而会对细节失去敏感度写得太短又容易在错误的场景被错误调用。我自己的经验是描述文件整体的可读长度控制在两三百字左右把关键信息都塞进去其余废话一律砍掉。3.3 编写核心逻辑核心逻辑的编写要分两种情况来说。第一种是纯提示词型 Skill核心逻辑全靠 SKILL.md 里的执行流程描述。这种 Skill 的关键是流程描述要结构化、步骤要编号、语言要肯定。我举个实际的例子假设你写一个“代码审查 Skill”执行流程可以这样写读取用户提供的代码文件路径或 diff 内容将其作为审查对象。根据文件扩展名或内容特征识别编程语言和框架类型。按文件逐个审查每条问题统一标记严重程度分别是 critical、major、minor 三个等级。对于每条问题必须同时包含问题描述、复现方式、修复建议三部分内容。审查结束后汇总所有问题按严重程度从高到低排序生成 Markdown 报告。步骤编号的好处是模型在处理长流程的时候不容易迷路。同时每个步骤里尽量把“判断标准”和“输出格式”写清楚比如“如果发现变量被赋值后从未使用标记为 minor 级别问题”这样模型就不会凭感觉定严重程度。第二种是工具调用型 Skill核心逻辑里会有工具回调和参数映射。写这类 Skill 时最重要的事情是给每个工具写清楚参数说明。要为每个关键函数写详细的 docstring明确每个参数的类型、取值范围、默认值和注意事项因为模型生成调用参数时很大程度上依赖参数说明文字的完整度。比如一个 get_diff 函数描述里应该写明“参数 repo_path 是仓库本地绝对路径requiredTrue参数 pr_number 是 PR 编号optionalTrue如果传了则返回该 PR 的 diff否则返回当前分支的未提交改动”。这样的描述能极大减少模型传错参数的概率。3.4 完整的测试与迭代写完之后一定不能直接扔到生产环境先做一轮完整测试再说。我的测试流程是这样的提前准备 5 到 10 个有代表性的用户请求分别覆盖几种情况明显应该触发这个 Skill 的请求、触发条件比较模糊但可以从上下文判断的请求、完全不应该触发这个 Skill 的请求。为什么要包括“不应该触发”的测试因为 Skill 描述写糊了模型就会像个乱开枪的枪手什么都往这个 Skill 上套。逐个测试并记录关键信息模型在第一步选择了哪个 Skill、执行了哪些步骤、每一步的输出是否符合预期、最终输出格式是否正确。这些记录是后期迭代的依据不记录靠拍脑袋改来改去也不知道改对了没有。对失败案例复盘时要找到原因层级是描述文件的问题导致没有触发还是流程描述有歧义导致步骤错乱还是工具输出不稳定导致下游拿不到数据定位到具体层级再动手改不要只盯着一个文件反复动。迭代的核心原则是一次只改一处。改完重新跑全部测试用例确认之前的正常行为没有被破坏。这个原则我强调很多次了因为我自己就是吃过亏的人以前总想一次性把描述、流程、输出模板全改一遍结果改完之后出了问题根本不知道是哪个改动引起的排查成本直接翻倍。4. 常见问题与排查技巧实录4.1 模型不调用 Skill怎么办这是所有 Skill 开发者都会撞上的问题几乎每个人都遇到过明明 Skill 写得挺仔细但模型就是不触发。我的排查顺序基本是固定的先检查描述文件。触发场景部分是不是用了用户真正会使用的语言如果用户说“帮我看看这个仓库有没有什么问题”你的描述里却写的是“代码审查能力调用”那模型确实很难把它关联起来。触达用户的语言习惯这是第一优先级。再检查模型本身的能力边界。有些轻量级模型在动态选择 Skill 上的能力较弱换个能力更强的模型或者改用规则路由效果立竿见影。还要检查是不是有多个 Skill 描述太像。模型对相似描述是很敏感的同时存在多个功能接近的 Skill它很容易选错或者干脆都不选。这时候可以把同类能力合并或者把描述中的场景差异写得更明显让模型一眼就能分辨。4.2 模型调用了 Skill但步骤执行混乱这种情况一般出在流程描述上。流程太长、步骤顺序不明确、相邻步骤之间的逻辑没交代清楚模型就容易在中间跑偏。解决办法是精简流程描述把 SKILL.md 里的执行步骤压到核心的几大步每一个步骤都给出明确的输入输出。另外在流程描述里加上“异常兜底指令”告诉模型如果某一步失败应该怎么处理比如“如果读取文件失败直接向用户报告错误原因不要尝试续写后续步骤”。这个兜底逻辑非常重要没有它模型遇到异常时会疯狂尝试重新调用或者基于错误结果继续往下编最后给出一份完全不可信的输出。4.3 输出格式不稳定如果 Skill 的输出有时是 JSON、有时是 Markdown、有时是一段不知所以然的文字最直接的办法是提供输出模板。在描述文件或执行流程中直接放一个完整的输出示例模型照着示例生成的准确率要比只看格式描述高得多。比如你要让模型输出一份 JSON 格式的修复建议就给它一个字段完整的 JSON 示例并注明每个字段的含义、必填项和取值规范。如果后续解析端要求字段必须齐全这个模板的作用就是决定性的。4.4 避坑清单下面这份清单是我自己做项目时攒下来的每条都对应过一次真实的教训不要在描述文件里堆砌“高端术语”要写用户真正常说的、口语化的表达。术语是给开发者看的描述文件是给模型看的模型服务的是用户所以它需要理解的是用户的表达方式。不要在一个 Skill 里塞太多工具。能控制在三个以内的工具调用就不要用五个工具多了模型选错工具的概率是成倍增长的。工具链一长整个 Skill 的稳定性一定会下降。不要把输出格式交给模型的自由发挥。有模板一定给模板这句话我反复强调都不为过。不要忽略错误处理。中间步骤失败时Skill 要么回退到安全路径要么给用户一个清晰的说明而不是沉默下去或者硬凑一个错误结果。不要频繁大改 Skill 的描述。Skill 描述微调都会引起 Agent 在决策行为上的连锁反应频繁改动会让系统处于不稳定状态。小步迭代一次改一处改动后至少稳定观察一段时间再决定下一步。5. 一些个人经验和收尾建议5.1 从实际使用中总结的方法如果让我给新手一个最简单的入手路径我会说先别想着一步到位写出特别复杂的 Skill。挑一个你每天都会重复做的小任务比如整理阅读笔记、把会议记录变成待办清单、给临时文件做分类把它写成一个极简的 Skill完整跑通再在这个基础上逐步加复杂流程。这个过程的收益非常大。你会完整体会到“触发—执行—输出”这个循环会亲眼看到哪些环节是模型自己搞不定的哪些环节是因为描述文件没有写清楚哪些工具参数是模型理解不了的。这些一手经验比看一百篇教程都管用。等你在小任务上形成了手感再去写那些跨工具、长流程的复杂 Skill思路会清晰得多。还有一点是关于使用的Skill 写出来不是放在那里吃灰的一定要在真实场景里持续使用。你会发现同一个 Skill 用了一两个星期之后你能从使用记录里看出很多设计之初根本想不到的新需求。比如用户经常问“可不可以也支持这种格式”那就是你下一个迭代的方向。Skill 是持续演化的产物唯一不变的真理就是“用起来才能发现真正的问题”。5.2 最后再分享一个小技巧分享一个我觉得非常实用但很少见人提到的技巧在 SKILL.md 的末尾加一个“测试用例”字段把设计这个 Skill 时的代表性用户请求直接写进去。比如这个 Skill 适用的请求示例、需要返回的输出示例、以及一些边界情况的应对说明。这样做有两个好处。第一任何接手这个 Skill 的开发者或者以后的你自己看完测试用例就能快速理解这个 Skill 的预期行为比读一大堆设计文档有效得多。第二你每次修改描述文件或核心逻辑之后可以直接复制这些测试用例去跑回归不用每次都苦思冥想新测试数据。我在好几个项目里都这样做了维护效率提升非常明显。这个技巧看起来不起眼但它在实际项目中的价值远远超过你的想象。养成了这个习惯之后你会发现 Skill 的可维护性不再是靠记忆而是靠文档里的真实用例在支撑。