做 agent 开发这半年我最大的感受可以用一句话概括模型的能力上限是固定的但你给它的“操作说明书”写得够不够好直接决定了它在你手里是玩具还是生产力工具。这也是我最近一直折腾 agent skills 的根本原因。尤其是 Claude 这类产品把 skills 作为正式能力开放之后整个开发范式发生了肉眼可见的变化——以前我们靠堆提示词让模型“尽力而为”现在可以把一整套操作流程、业务规范、工具脚本打包成标准化的技能单元让 agent 在正确的时机调用稳定地产出符合预期的结果。这篇文章想把从概念到落地的东西一次性聊透skills 到底是什么、和 tools、workflows 怎么区分、从零写一个能用的 skill 需要走哪些步骤、调试过程中我踩过哪些坑、以及安全边界该怎么划。适合正在做 agent 开发、想把团队经验固化成可复用能力、或者纯粹对“怎么让 AI 稳定完成多步骤任务”好奇的人。下面直接进入正题。1. 先搞清楚核心概念agent skills到底是什么1.1 skills到底在解决什么问题我先用一个最生活化的类比来解释。想象你带了一个刚入职的实习生把他叫到工位上说“处理一下今天的工单”。他大概率会一脸茫然。你得告诉他工单在哪里看、判断标准是什么、先做什么后做什么、遇到异常找谁、最终输出用什么格式。这一整套“教会他干活”的材料本质上就是一个 skill。在 agent 的世界里事情是一样的。大模型天生知道很多事实性知识它能写诗、能算数、能解释概念但它不知道你团队内部的流程、你项目里的代码规范、你期望的周报格式、你业务场景中的专有名词和判断口径。skills 就是把这些“非模型默认知识”打包成模型可以读取的标准化文件让 agent 在需要的时候按图索骥。具体到落地形态一个 skill 通常是一个目录里面至少包含一份主指令文件常见命名是 SKILL.md再配上若干辅助文件——Python 脚本、JSON 模板、参考样例、数据字典。模型读到 SKILL.md 之后就能理解“这个技能是干什么的、什么时候用、怎么用、产出物是什么”。换句话说skills 解决的是“模型不知道但你希望它遵守的那部分知识怎么给到它”的问题它补的是程序性知识、领域规范和组织约定。这里有个关键点容易被忽略skills 不是把模型的“能力”变强了而是把模型的“行为”校准了。模型本身没有变但因为它读取了更精确的操作指令表现出的可靠性和一致性会肉眼可见地提升。这也是我后来为什么把所有重复性任务都往 skill 里装的原因——同样的模型底座装了 skill 和没装 skill干活质量完全是两个档次。1.2 skills、tools、workflows的边界很多人一开始分不清 tool、skill、workflow 三者的区别我最初也在这个问题上绕了很久。简单说tool 是“手”skill 是“脑子里的操作手册”workflow 是“已经钉死的流水线”。tool 是 agent 可以直接调用的函数输入输出都是结构化的单次调用、无状态。比如查询天气、发送邮件、执行一段代码。它解决的是“具体动作怎么做”的问题。skill 是“完成一类任务的方法论”它可能包含多个步骤、多次调用 tool、内部有判断分支。比如“把一份会议记录转换成项目周报”就是一个 skill内部可能要调用转录工具、摘要工具、文本格式化脚本最后按模板生成文档。workflow 更偏编排是预先定义好的固定流程适合那种 100% 确定、不允许模型自由发挥的场景。skill 和 workflow 最大的区别在于skill 保留了模型在步骤内部的判断空间workflow 则把每一步都钉死了。用一个表格来对比更直观维度ToolSkillWorkflow本质可调用的函数可复用的操作手册固定流程编排粒度单次调用一组操作加决策规则多步骤串联灵活性固定输入输出步骤内允许模型判断通常较少模型自由决策典型例子search_web(query)“会议纪要到周报”定时数据同步管道经常有人问“有了 skillstools 是不是就不需要了”答案是否定的。skills 内部恰恰要调用 tools 来落地具体动作。skills 解决的是“做什么、按什么顺序、按什么标准做”的问题tools 解决的是“具体动作怎么执行”的问题。二者是协作关系不是替代关系。理解了这层关系后面写 skill 的时候你就会自然地去思考哪些环节交给脚本哪些环节留给模型判断。2. skill的底层设计一份好SKILL.md是怎么炼成的2.1 标准目录结构每个文件夹都有自己的职责一个可维护的 skill目录结构大致长这样my-skill/ ├── SKILL.md # 主指令文件 ├── scripts/ # 可执行脚本 │ └── parse_dates.py ├── templates/ # 输出模板 │ └── weekly_report.md ├── examples/ # 输入输出示例 │ ├── sample_input.md │ └── expected_output.md └── data/ # 技能运行需要的静态数据 └── category_map.json这个结构不是拍脑袋定的。SKILL.md 是模型最先读取的文件决定了它对整个技能的认知框架scripts 放可执行逻辑负责模型不擅长的精确计算templates 保证输出格式的稳定性模型在生成最终结果时可以直接套用模板examples 目录存放典型输入和期望输出相当于“范例教学”模型看到具体例子后对抽象指令的理解会准确很多。这里有一条实际经验examples 目录的价值被大多数人低估了。模型在 few-shot 场景下的表现远好于 zero-shot你给一个高质量的输入-输出对效果顶得上在 SKILL.md 里多写几百字抽象描述。我自己在“会议纪要转周报”这个技能里放了三个示例分别对应简短会议、长会议、包含大量决议的会议模型在处理这三种情况时的表现几乎没有偏离过预期。2.2 SKILL.md的内容组织从“是什么”到“怎么用”我把一份合格的 SKILL.md 拆成六个模块每个模块都有明确的目的技能名称和一句话概述让模型一眼判断“这个技能是不是当前任务需要的”。适用条件和触发信号明确“什么时候用、什么时候不要用”避免误触发。任务目标和成功标准定义“做完”和“做好”分别是什么样给模型提供自查依据。执行步骤按顺序拆解操作流程每步给出输入、处理、输出。约束和禁忌哪些事绝对不能做、哪些格式必须遵守。自定义规则领域专有规则也就是模型默认不知道的那部分知识。这六块里面最容易被忽略的是“成功标准”。没有成功标准的时候模型做完之后不知道自己对不对它会在结果里塞一堆无关内容来“显得努力”。我在 skill 里强制加了一段 self-check 清单让模型交付前逐项自查输出质量立刻上了一个台阶。举个例子在周报技能里我写的成功标准是输出为 Markdown 格式、各议题归类准确、每个待办事项都有负责人和截止时间、风险项不超过三条时列全超过三条时按严重程度取前三。有了这些标准模型在交付前会自己去对照检查而不是把一堆信息平铺出来让你自己整理。2.3 指令写作的三条铁律具体、分层、可验证写 skill 指令和写提示词有一个很大的不同提示词是给模型“发挥”的skill 是给模型“执行”的。所以措辞上的要求完全不同。我总结下来有三条铁律。第一具体避免抽象形容词。“生成一份专业的周报”是不合格的“周报必须包含本周完成事项按优先级排序、风险与阻塞、下周计划、每个事项标注工时”才是合格的。抽象描述留给模型太多解释空间你得到的往往是“看起来很专业但根本不是你想要的东西”。第二分层把总目标和子步骤区分开。SKILL.md 里先写总目标再用编号把步骤拆开模型对顺序的理解会准确很多。我见过很多人把需求揉成一坨文本模型经常捡了芝麻丢西瓜。步骤之间最好还要注明“这一步的输出是下一步的输入”相当于给模型建立一条明确的工作链。第三可验证。每步最好有“产出物”和“检查方式”。比如“从输入文档中提取所有关键词输出为 JSON 数组”就比“分析文档内容”强十倍。模型执行完提取后哪怕它不确定自己对不对也能通过“数组格式是否合法”来自查。这个原则在写脚本接口时尤其重要——你给模型一个函数接口必须讲清楚参数格式和返回值格式模型才可能正确调用它。3. 从零开发一个可复用的skill完整实操记录3.1 场景选择为什么拿“会议纪要转周报”练手我建议第一次开发 skill 的人找一个“你每周都要做、流程相对固定、但每次输入都不太一样”的任务。我在团队里最常用的练手场景是把原始会议纪要转换成项目周报。这个场景有三个天生的优势。第一它是典型的多步骤任务。清洗纪要、按议题归类、提炼进展、标注风险、生成周报模板每一步都有明确的输入输出非常适合展示 skill 的结构化能力。第二输入差异天然存在。不同会议的纪要在格式、详略、语言风格上完全不同这能很好地测试技能的泛化能力。如果只拿格式统一的输入来测试技能看起来很好一旦遇到真实世界的脏数据就会露馅。第三团队内部已有成熟的周报规范。我可以把规范原封不动地固化成 skill直接验证“经验沉淀”这件事是否可行。如果你的团队也有类似的规范文档那就是现成的 skill 素材。3.2 第一版skill的实现细节先写 SKILL.md 的草稿按上面说的六模块框架来组织。我演示一下关键部分# 会议纪要到项目周报 ## 功能概述 将非结构化的会议纪要转换为结构化项目周报适用于每周团队周会后的周报生成。 ## 触发条件 当用户提供会议纪要、讨论记录、录音转写文本并要求生成周报、汇总进展时使用。 ## 不适用场景 - 输入已经是结构化周报时不要重复转换 - 用户仅要求总结要点时直接总结不要套用周报模板 ## 执行步骤 1. 通读全文识别参与者、议题、决议、待办事项 2. 按议题维度归类区分“已完成/进行中/阻塞/计划” 3. 对每个议题提炼进展描述保留关键数据 4. 识别风险项标注严重程度和负责人 5. 按 templates/weekly_report.md 生成周报 ## 成功标准 - 输出为 Markdown 格式各议题归类准确 - 每个待办事项都有负责人和截止时间 - 风险项不超过 3 条时列全超过 3 条时按严重程度取前 3同时我写了一个 Python 脚本负责最“笨”但最精确的部分——时间解析和优先级排序def parse_due_date(raw_text): # 从“下周五”“3天后”这类自然语言中解析日期 # 解析失败时返回 None由模型根据上下文补充 ... def sort_priority(items): # 按严重程度排序P0 P1 P2 ...这里要说明一个设计决策为什么不把所有逻辑都让模型做而要写脚本因为模型在“计算日期”这种精确任务上可靠性不够但在“提炼语义、判断归属”这种任务上表现很好。让脚本做它擅长的精确计算让模型做它擅长的语义理解这就是 skill 内部分工的核心思想。你写 skill 时也要时刻问自己这一步是交给代码还是交给模型判断标准只有一个——谁做这件事更可靠。3.3 测试、回退与迭代的真实记录写完第一版我收集了过去四周的真实会议纪要来测试结果挺打脸的。第一次跑完周报里出现了三个问题议题归类把“技术方案讨论”归到了“项目进展”里待办事项漏掉了纪要里用括号标注的“待确认”项风险部分过度使用“重大风险”这种词把一个小问题写得非常严重。我的调整方法是三步走。第一步修改 SKILL.md 中的归类规则明确“技术方案讨论”在没有明确结论时归入“调研/决策中”分类。第二步在步骤 2 里增加一条“注意包含括号备注的待办事项”。第三步在风险判断中加入量化标准影响范围、持续时间、是否有替代方案三个维度综合判定。调整完再跑同样一批数据结果准确率从六七成提升到了九成以上。这个过程验证了我一直相信的一件事skill 的质量不是一次写出来的而是在真实数据上反复打磨出来的。你写的每一条规则最好都有实际失败案例作为依据不然就只是在写“正确的废话”。给 skill 加上版本号和变更日志也是从这个时候开始的——因为你很快会发现没有版本记录的迭代就是一场灾难。4. 高频问题排查实录为什么skill会失灵4.1 我遇到过的六个高频问题问题现象根因解决方案agent 该用 skill 时不用触发描述太窄模型没意识到匹配在触发条件中补充同义表述和反例不该用时乱用描述太泛模型什么都想套增加“不适用场景”清单明确负面信号执行到一半自己改流程步骤顺序说明不够强制步骤前加“必须严格按顺序执行不得跳步”输出格式不稳定模板约束不足提供模板文件并在 SKILL.md 中标注“必须套用模板”反复调用同一个脚本缺少缓存或中间变量说明在步骤中明确“每个脚本只调用一次保存结果到变量”模型不知道 skill 更新了版本信息缺失在 SKILL.md 中记录版本号和变更日志第三行那个“执行到一半自己改流程”是我遇到最多的。模型天然有“自由发挥”的倾向你让它按五步走它走到第三步觉得“这里可以直接出结果”就跳过了。后来我在 SKILL.md 顶部用加粗写了“本技能所有步骤必须按顺序执行不得跳过、合并或调整顺序”并且每一步都写清楚“这一步的输入来自上一步的产出”问题才基本消失。第四行“输出格式不稳定”也很常见。模型对“大概什么样”的理解和你的预期之间永远有偏差。解决方法是给模板并且在指令里直接写“最终输出必须完全套用模板包括标题层级和字段顺序”。模板文件本身要放在 templates 目录里让模型直接读取而不是在指令里描述模板长什么样。4.2 三步定位法问题到底出在哪一环skill 出问题时先别急着改文本。我建议按下面的顺序定位问题。第一步看触发环节。这一步最容易被忽略。先确认 agent 到底有没有调用这个 skill。没有调用说明是触发描述的问题而不是技能内容的问题。有调用但结果不对才进入下一步。怎么确认直接在调试环境里打印调用日志或者让 agent 在决策时输出“选择技能的思考过程”。第二步做隔离测试。把 skill 从工作流里摘出来单独用一份干净输入跑一遍看是否复现。复现了说明问题在 skill 内部不复现说明是上游数据或上下文干扰问题。上下文干扰是个隐蔽杀手——当上下文里塞了大量无关对话时模型对 skill 指令的遵循度会明显下降。第三步做步骤二分。把 SKILL.md 从五步缩到第一步跑通后逐步加回找到引出错误的那一步。这个过程很像调试代码的二分法能很快定位是“哪一步的指令描述有歧义”还是“哪一步依赖的脚本有 bug”。我遇到过一种情况前四步都正常第五步出错排查了半天发现是脚本里日期解析函数对“下周一”这个表述处理不对跟模型指令一点关系都没有。5. 安全与版本管理让skill活得久5.1 安全边界权限最小化是底线skills 一旦接入真实系统安全问题就必须正视。一个 skill 本质上是一段可以被模型解释并执行的指令加代码攻击面来自两个方向skill 内容本身是否安全以及 skill 运行时是否有越权风险。先说内容安全。如果你引入第三方 skill一定要审查它的脚本代码。我见过一些“看起来很美好”的 skill 包里面的 Python 脚本实际上会读取环境变量、扫描敏感文件。原则很简单不运行不信任的代码不加载不透明的脚本来源不明的 skill 一律先隔离审查再启用。审查时重点看 scripts 目录下有没有可疑的文件操作、网络请求、子进程调用。再说权限边界。我给团队定了几条硬规则skill 内所有脚本必须运行在受限环境禁止无理由访问网络文件读写范围限制在指定工作区涉及删除、覆盖、发送等破坏性操作前必须经过用户确认所有外部调用必须记录日志。权限最小化这几个字在设计 skill 的第一天就要写进规范而不是出事之后再补。agent 安全这个话题最近讨论很多本质上和传统软件安全是相通的输入校验、最小权限、操作审计、异常回滚。只不过 skill 的“代码”里掺杂了自然语言指令审查难度更大更需要你在引入每个 skill 时多留个心眼。5.2 版本管理与生态共享skill 是代码资产不是一次性提示词所以版本管理是必须的。我把每个 skill 做成 Git 仓库SKILL.md 的变更记录单独维护每次更新都写 changelog。这样当模型行为异常时可以快速回退到上一个稳定版本并且能找到“是哪次改动引入了问题”。这套做法在团队协作时的价值更大。不同成员可以 fork 同一个 skill 做各自的实验验证有效后再合并回主干。技能更新之后下游所有引用它的 agent 都会自动感知到新版本——前提是你在 SKILL.md 里写了版本号并且让 agent 在调用前检查版本。关于共享现在已经有了一些 skills 下载平台和社区市场。这意味着你可以把团队内部验证过的技能发布出去也可以吸收别人沉淀的成果。我的建议是下载的 skill 一定要做适配性测试。别人的指令文本里可能隐含了他团队的特殊约定直接拿过来用大概率水土不服。正确姿势是把它当“参考实现”看懂设计思路后改写成适配自己场景的版本。未来 agent 开发的竞争点很可能不在模型本身而在技能生态。哪个团队能把最佳实践快速固化成高质量 skill哪个团队就能在同样的模型底座上产出更高效率。这也是我现在特别关注 skills 生态的原因——这个领域还远没到定型的时候现在积累的经验很快会变成硬通货。6. 最后说几点我的个人体会做 agent skills 这段时间我最深的感受是这东西本质上是在做“知识工程”的现代版本。以前我们做专家系统是把人类专家的经验转成规则现在做 skill是把团队的最佳实践转成模型可读的指令。技术术语变了很多但底层逻辑一脉相承——能不能把隐性的经验显性化决定了你的 agent 是“能聊天的玩具”还是“能干活的生产力工具”。如果你也想开始不用等什么完美时机。挑一个你每周都要做、做得烦、但规律性很强的任务把它变成你人生中的第一个 skill。第一版粗糙没关系只要你坚持用真实数据去打磨它三个月后回头看你会发现自己对“怎么让模型稳定干活”这件事的理解完全不一样了。用小任务入门用真实数据迭代剩下的时间会给你答案。
