先说一个我最近高频遇到的场景有人把 Agent 搭好之后在系统提示里塞了一大段“你是一个数据处理专家请按以下步骤清洗 CSV第一步做什么第二步做什么……”然后跑起来发现 Agent 要么生搬硬套要么步骤执行到一半自己发挥最后输出完全不可控。于是他们得出结论框架不行模型不够聪明。这个结论我不同意。问题大概率出在你把技能写成了提示词模板。这两样东西听起来很像实际差距非常大。今天我聊的 SKILL.md就是目前主流 Agent 技能规范里用来定义“技能”的核心文件。如果你正在做 Agent 开发、维护技能库或者你团队里有人整天用“提示词模板”来伪装技能那这篇文章值得花十分钟读完。我会从原理到实战把“技能”和“提示词模板”的边界彻底讲清楚。1. 为什么说“提示词模板”根本不是技能1.1 提示词模板只能“告诉”不能“教会”先看一个最常见的做法。很多人把技能定义成一个指令集合比如你是一个 Python 脚本编写助手。当用户要求写脚本时请 1. 先询问脚本用途 2. 再确认输入输出格式 3. 写出完整代码 4. 最后写使用说明这段文字有没有用有用。但它本质上只是“一段约束模型行为的文本”。模型读完之后能不能稳定按这个流程走取决于模型的临场记忆和上下文长度。一旦对话变长、任务变复杂这段指令就会被稀释Agent 很容易丢掉中间步骤甚至自己加戏。原因很简单提示词模板依赖的是模型对文本的“理解”而理解是有概率的不是确定的。而且提示词模板天然缺少两个关键东西可执行的参考实现和可验证的边界条件。你说“请清洗 CSV”模型会清洗但清洗到什么程度算干净空值怎么处理日期格式要不要统一如果这些没有明确约定模型每次执行的随机性都会被放大。所以你会发现同一个提示词上午跑和下午跑效果可能是两个样。1.2 Skill 的真实构成不只是“一段话”真正意义上的 Agent Skill是一个完整的、自包含的能力单元。它由一个目录承载核心是 SKILL.md 文件同时可以附带脚本、参考文档、资源文件等。SKILL.md 本身虽然也是 Markdown但它有自己的结构约定包含 YAML frontmatter 元数据和正文指令目标不是“让模型即兴发挥”而是“让模型在没有额外知识的情况下也能按照明确流程完成一项任务”。打个比方提示词模板像是一张写着“西红柿炒蛋怎么做”的便条看完还得靠厨师的个人经验而一个完整的 Skill 像是把菜谱、备菜清单、火候对照表、常见翻车补救方案全放在一个料理包里。厨师Agent拿到的不只是一句话而是完整的工作手册和工具。当前主流的 Agent 技能规范里SKILL.md 就是技能目录的入口文件。模型在运行时会先读取这个文件判断这个技能适不适合当前任务然后决定是否启用。所以你写的不只是一篇文档而是 Agent 的“决策依据 执行手册”。这个定位上的差别决定了我们不能用写提示词模板的思路来写它。2. SKILL.md 的文件结构与 metadata 设计要点2.1 frontmatter 里的 name 和 description 是“召回开关”一个标准 SKILL.md 最最容易被忽略、但又最影响效果的部分就是文件开头的 YAML frontmatter。它长这样--- name: csv_cleaner description: 清洗 CSV 数据文件适用于处理缺失值、统一日期格式、去重等场景。当用户上传 csv 文件或要求整理表格数据时使用。 ---name是技能的唯一标识通常用下划线命名全小写。description则是模型决定是否调用这个技能的“召回开关”。你写得太泛比如“数据处理工具”那模型在任何跟数据沾边的任务里都可能调它哪怕用户只是想问一个统计概念写得太窄也不行比如“只处理含日期列的 CSV”那遇到确实需要清洗但没有日期字段的文件它又会漏召回。我的经验是description 至少包含三块信息这个能力是干什么的、适用什么场景、在什么情况下不要用。比如刚才的例子加一句“不适用于数据可视化或数据分析报告生成”就能明显减少误调用。别小看这句“不适用”它和“适用”同等重要。另外frontmatter 里不同规范版本还支持其他字段。有的支持allowed-tools用来限制技能执行期间 Agent 可以用哪些工具这能有效防止模型在技能运行中途跑偏去调无关工具有的支持version字段方便技能库做版本管理。我建议从第一天就写上version: 1.0.0等到后面迭代多了你会感激这个习惯。2.2 正文部分指令密度、边界条件和示例缺一不可越过 frontmatter 之后的正文是技能的主题内容。很多人在这里犯的毛病是“把 SKILL.md 写成操作手册的目录”只有步骤标题没有细节。你要知道SKILL.md 的读者不是人是 Agent。Agent 不会自动脑补“合适”和“大致”是什么意思。正文我习惯按这样的结构组织先写“何时使用”再用步骤/小节描述执行流程然后在关键步骤里写明输入输出约定、边界条件、常见错误。比如你写“清洗缺失值”不能只说“删除空行”要说清楚空值占比低于 5% 的列直接删除所在行空值占比超过 40% 的列整列删除其余情况用列均值或中位数填充并且在输出报告中注明填充策略这种密度才是 SKILL.md 该有的样子。Agent 拿到手才知道怎么做而且每次做的结果是一致的。还有一个经常被忽略的点给反例。正例告诉 Agent 什么是正确的反例告诉它怎么避免错误。我在技能里通常会加一节“常见错误”比如“不要把 ID 列误判为数值列做均值填充”“不要在清洗前破坏原始文件必须保留原始副本”。这些都是实际跑出来的血泪教训写进去之后Agent 的翻车概率会明显下降。2.3 配套脚本和资源让技能从“文本”变成“工具”SKILL.md 真正的威力在于它可以引用外部资源。你要做一个 CSV 清洗技能完全可以把清洗逻辑写成一个 Python 脚本然后在 SKILL.md 里告诉 Agent“执行过程中优先参考 scripts/clean.py如果脚本执行失败再走手动流程”。这样技能就从一个“概念”变成了“可复现的工具”。在规范允许的范围内SKILL.md 可以通过相对路径引用同一技能目录下的文件。常见的组织方式csv-cleaner/ SKILL.md scripts/ clean.py references/ column-type-guide.mdSKILL.md 里用类似“参考脚本 scripts/clean.py 的normalize_dates函数”这样的写法来引用Agent 在需要时会自行读取这些文件。不过要明确一点技能目录里的脚本不是给 Agent 随便乱跑的规范通常对执行权限有限制。这时候 SKILL.md 里就要写清楚“允许运行哪些命令禁止运行哪些命令”避免出现 Agent 拿着脚本去做超出技能范围的事。3. 实战把一个“提示词模板”改造成可执行的 Skill3.1 原版提示词长什么样为了直观我用一个真实发生过的场景来演示。假设团队需要一个“日报生成助手”最早的实现方式是一段提示词模板你是日报生成助手。用户会给你当天的工作内容请生成一份日报。 要求 1. 按项目分组 2. 每个项目写出完成了什么、遇到什么问题、明天计划 3. 使用简洁的语言 4. 格式要清晰看起来没问题对吧实际跑起来问题一大堆。Agent 经常分不清“完成了什么”和“明天计划”的时态遇到用户只给一句话“今天在搞支付模块”时它要么编造细节要么直接拒绝生成。最关键的是不同人给的内容粒度不一样有的给 50 字有的给 2000 字Agent 不知道该怎么取舍结果生成的日报篇幅忽长忽短质量完全不可控。3.2 改造后的 SKILL.md 长什么样我们把它改造成一个完整技能。目录结构如下daily-report/ SKILL.md scripts/ split_by_project.py references/ writing-style-guide.mdSKILL.md 的主体内容我基于踩坑经验做了大幅重构核心部分是这样设计描述的--- name: daily_report description: 根据用户提供的当天工作内容生成结构化日报按项目分组并在每个项目下输出进展、阻碍和明日计划。适用于工作报告、项目日报、个人总结场景。当用户发来的内容少于三句话或只表达情绪感受时不要使用。 --- # Daily Report 技能 ## 输入约定 - 用户输入可以是自由文本也可以是时间流水账。 - 若输入包含多个项目先用 scripts/split_by_project.py 按关键词切分。 - 若输入信息不足必须向用户追问“项目名称”“进展百分比”“阻塞问题”不得自行编造。 ## 输出格式 - 每个项目段包含项目名、今日进展精确到具体事项、遇到的问题没有则写“无”、明日计划。 - 整体篇幅控制在 400 字以内按 5W1H 原则压缩。 - 参考 references/writing-style-guide.md 中的语气要求。 ## 执行步骤 1. 读取用户输入识别项目关键词。 2. 对长度超过 2000 字的输入调用脚本切分后再归类。 3. 按输出格式生成日报先输出草稿再自查。 4. 自查项是否有编造是否遗漏阻塞问题是否超过字数限制 ## 常见错误 - 不要使用“大概”“应该”这类模糊表述 - 不要把用户没有提到的功能写成“已完成” - 不要同时输出两种以上日报格式看到区别没有原来模板里的 4 条要求被细化成了“输入约定 输出格式 执行步骤 常见错误”四个模块。关键不是格式变了而是 Agent 在每个环节都有了明确的判断依据。比如“输入不足必须追问”这就堵住了编造内容的口子“超过 2000 字用脚本切分”这就解决了长输入处理不稳定的问题。3.3 为什么改造后 Agent 的表现明显变好这套改造上线后的效果比预期还明显。最直观的变化有两个一是生成日报的置信度变得可预测不再出现今天是三行、明天是三百字的极端情况二是面对模糊输入时Agent 的行为从“硬着头皮生成”变成了“主动追问”这恰好符合用户对助手类 Agent 的期待。背后的原因其实很简单。提示词模板里的“使用简洁的语言”“格式要清晰”都属于主观判断模型无法量化执行。而 SKILL.md 里的“400 字以内”“必须追问”“不得编造”都是可验证的约束模型在执行时可以被引导朝向可校验的方向。再加上脚本和参考文档的兜底技能从“靠模型理解”转变成“按规范复现”。这也是我一直强调的写技能本质上是在写一份机器可执行的 SOP而不是在写一份人类的操作建议。4. 调优与避坑让技能真正稳定可用4.1 description 太泛导致误召回我踩过的坑这个坑我栽过一次大的。早期我负责的技能库里有一个“数据可视化助手”description 写的是“处理数据并在画布上生成图表”。听起来没毛病但上线后疯狂被误调用——用户问“这个数据趋势怎么样”Agent 就直接调用它去画图完全不先分析数据指标。后来我把 description 改成“仅当用户明确要求生成图表折线图、柱状图、散点图时使用若用户仅要求数据分析结论应使用 data_analysis 技能”误召回率立刻降了一个量级。教训很直接description 不是写给人看的优雅介绍而是一个精确的过滤条件。你宁可写得啰嗦一点也要把边界写清楚。尤其是当技能库里的技能数量超过 10 个时技能之间经常发生“抢单”八成都是 description 写得太宽导致的。4.2 不能只定“过程”还要定“结果校验”还有一个常见误区SKILL.md 只写了执行步骤没写结果校验方式。比如你让 Agent 生成 JSON 配置以前我会写“输出 JSON”但 Agent 偶发会输出 Markdown 代码块包裹的 JSON或者输出不合法 JSON。为了这个我专门在技能的“结果校验”部分写了输出必须是纯 JSON不包含代码块标记。 生成后自己解析一遍解析失败则重新生成。这算是给 Agent 加了一个“质检环节”。从那以后这个技能的 JSON 格式错误率基本归零。原理上这相当于把错误检测内嵌到了技能的闭环里让 Agent 在交付前多一道自我纠错。凡是涉及生成代码、配置文件、结构化数据的技能我都强烈建议加上“结果校验”环节。4.3 版本管理与多技能协作SKILL.md 作为文本文件同样会遇到版本演化的问题。技能迭代到一定次数你会发现“上一版的行为”和“这一版的行为”同时存在于用户的印象里。这时候 frontmatter 里的 version 字段就派上用场了。我习惯在每个技能目录里放一个 CHANGELOG.md记录行为变更点然后在 SKILL.md 里注释版本号。这样出了问题能快速回溯是哪个版本引入的。多技能协作方面重点要防止技能之间的“相互干扰”。比如数据处理技能和 CSV 清洗技能从任务类型上高度重叠如果两个技能都会被同时召回Agent 可能先跑清洗又跑处理多了一遍无意义操作。我的做法是在 description 里显式声明“和 csv_cleaner 技能的区别”并在正文里加一句“如果用户上传的文件已经清洗过直接进入下一环节”。别嫌麻烦这就是 Agent 应用从 demo 走向生产环境必须抠的细节。4.4 调试技能时最有效的手段让 Agent 把推理过程写下来最后一个调试技巧。遇到技能表现不对的时候别急着改 SKILL.md 里的文字。我建议在技能里临时加一行“执行时把每一步所作选择和依据记录到备注字段”然后跑几个典型用例看 Agent 的真实决策路径。很多问题在输出结果层面看不出来但你一看它的推理过程就知道是哪一步理解偏了。这个方法帮我定位过不少诡异问题比如“Agent 明明读到了脚本路径但选择不执行”“Agent 把每步都写得很详细却忽略了最终要生成的文件”。等到问题定位清楚再把临时的记录指令删掉或者降级成“仅在调试模式输出”。这一步非常符合 Agent 开发的实际节奏先让过程可见再优化结果。5. 关于 Skill 库维护我最后再说几点实在的技术原理和实战案例都说完了最后聊一些我在技能库维护过程中积累的个人经验不一定成体系但每条都对应过真实问题。第一技能是一等公民应该像代码一样走 review。我见过很多团队把 SKILL.md 当作普通文档来维护谁都能改改完不评审结果就是技能描述前后矛盾、格式风格混乱。SKILL.md 本质上是给模型执行的代码如果它是确定性的逻辑你会放心让任何人随便改吗第二给技能配备“测试用例集”。每个技能目录下面除了 SKILL.md最好再加一个test-cases.md里面放 5 到 10 个典型的输入输出对。每次调整描述或步骤后用这些用例跑一遍看表现是否符合预期。不需要什么复杂框架跑一遍人工确认就行但一定要有这个过程。没有测试用例的保护一次小改动就可能让一个平时稳定运行的技能突然失效。第三技能数量要控制别贪多。有一些人喜欢把什么能力都往技能库里塞结果技能库膨胀到几十个描述互相交叉召回率直线下降。我的建议是先保核心高频场景每新增一个技能之前先想一想它和已有技能的场景边界是否足够清晰。宁可少而精不要多而全。第四SKILL.md 这套思路的最终目标是让 Agent 的能力“可组合、可复用、可验证”。如果你团队里有多个 Agent 项目建议把技能库抽象出来独立维护而不是每个项目各写各的。一个技能库能被多个 Agent 共享才真正体现出“技能”和“提示词模板”的本质差异——提示词模板是写死在单个配置里的而技能是可以在不同 Agent 之间迁移和复用的。最后再分享一个小技巧当你开始用 SKILL.md 写技能时可以先从改造最常用的一个提示词模板入手把它拆解成“输入约定、执行步骤、输出格式、结果校验”四段式。你自己对比一下改造前后的执行效果会比任何人给你讲道理都直观。我亲测过这个做法的正反馈非常快基本改完一个技能你就再也不想回头写提示词模板了。