看到“Skills 编写学习缆”这个标题我第一反应是估计把“学习路线”打成了“学习缆”。这并不影响判断因为这个领域我最近半年在好几轮实际项目里反复折腾过正好可以系统性地展开讲一讲。“Skills 编写”说白了就是给大模型代理写可复用的技能模块。很多做 AI 应用开发的朋友已经不再满足于“会调模型接口”而是开始面对一个更现实的问题怎么让代理稳定地完成一类复杂任务而不是每次都靠临时写一大段提示词去碰运气。Skills 就是解决这个问题的主力方案。如果你正在学提示词工程或者你想从“会聊天”升级到“会造 Agent”这篇文章值得你花二十分钟读一遍。下面我会按我自己的学习路径来写先讲清楚技能到底是什么再给出完整的学习路线然后带你看一个技能从需求到上线的全过程最后整理一份高频踩坑清单。整体偏实操尽量不堆砌概念。1. 先把“Skills 编写”到底是什么说清楚1.1 技能的本质给代理一本随取随用的工作手册很多教程喜欢把技能讲得很玄其实它就是一份“工作手册”。想象一下你请了一个非常聪明但缺乏经验的实习生他推理能力很强可每次干活都要你现场交代背景、流程、输出格式。技能就是你把这一整套说明提前写好放进一个文件里等代理遇到对应任务时它能自己把这本手册翻出来照着做。这里最关键的两个字是“按需加载”。代理在日常对话里上下文是有限的如果你把所有流程细节全塞在系统提示词里会占用大量上下文窗口既费钱又影响推理效果。技能的做法恰恰相反平时只暴露一个精简的“说明条目”等真正需要执行任务时代理才去读取完整指令内容。这个机制很像你在办公室备了一个工具柜平时你不知道锁里面有什么等到要拧螺丝了再打开柜子拿扳手。我早前踩过一个坑就是把技能理解成“一个更长的提示词文件”。不是的它更接近一套“带索引知识库”的指令系统。说明书正文、触发条件、使用示例、辅助参考资料甚至脚本都可以放在同一个技能目录里加载时机和方式也各有讲究。1.2 技能、提示词、插件三者的边界为了搞清楚“Skills 编写”到底学的是什么你可以把当前主流的扩展方式看成一条光谱。形态核心特点适合场景主要成本提示词一段文本写在系统提示或对话里一次性任务、探索性任务每次都要重写容易很长技能结构化指令包按需加载可复用反复执行同一类流程化任务前期设计成本高需要测试插件/工具可执行代码对接 API 或外部系统强逻辑、强外部依赖场景开发维护成本最高提示词是“你告诉它怎么做”技能是“你让它自己找到怎么做”插件是“你不用它想你替它做”。实践中很多人卡在提示词和插件之间觉得写提示词太不够用写插件又太重学完技能刚好能接上这个空档。要特别留意一个观点技能不是“提示词的下位替代”也不是“插件的穷人版”。它是独立的一层设计。好技能的优点在于它能把你对任务的领域经验、对模型行为的预判、对输出规范的约束全部沉淀成一个可维护的资产。这个资产能跨项目复制也能跟着模型升级而演进这是单纯提示词很难做到的。1.3 为什么“会写技能”值得当成一门单独技能来学如果你去看招聘信息和团队分工最近一年最大的变化是很多团队不再只招“提示词工程师”或者“大模型应用开发”而是要求这些人同时具备“把复杂任务抽象成可复用模块”的能力。技能编写刚好落在这个交叉点上。从两个角度看这个能力的重要性。对个人来说它是从“单次调优”走向“工程化交付”的关键一步。你写一百条提示词不如沉淀五个高质量技能前者的经验是碎片化的后者可以形成系统方法论。对团队来说技能文件天然适合做模板化管理和版本控制新人接手项目时不用翻聊天记录直接把技能目录读完就能理解整个业务逻辑。我自己最深的体会是写技能的过程逼着你把“模糊需求”变成“明确指令”。真实业务里很多需求是说不清楚的用户说“帮我整理一下会议纪要”但整理成什么样、包含哪些模块、信息缺失了怎么处理全是模糊地带。技能编写强迫你把这些模糊全部消解掉这个能力对任何技术岗位都通用。2. 我的六阶段学习路线2.1 路线图概览我把整个学习过程拆成六个阶段每个阶段都可以穿插实际练习不必等上一个完全学完再进下一个。阶段学习重点产出物预计时间一提示词工程基本功能写出稳定输出的复杂提示词2-3周二代理执行循环与模型行为边界理解代理为什么“不听话”1周三技能格式与加载机制跑通一个最小技能3-5天四模仿与重构改写三个别人的技能1-2周五测试与迭代用测试集验证技能持续进行六发布、复用与维护形成个人技能库持续进行这条路不复杂难点在于很多人愿意直接从第三阶段开始结果遇到问题又绕回第二阶段去补课。我建议还是按顺序走基础部分虽然看起来啰嗦但后面省的时间远多于前期投入。2.2 阶段一把提示词工程打牢会写技能的前提是你能把一段指令写到“不加额外解释模型也能稳定执行”的程度。这个阶段不要急着追求花哨技巧重点练四件事角色设定、背景信息、输出约束、示例驱动。很多人写提示词喜欢把角色写得特别满比如“你是一位拥有二十年经验的高级数据分析专家”但实测下来角色对结果的影响非常有限真正起作用的是约束条件和示例。我练这个阶段时用了一个笨办法每个提示词都强制要求自己写“必须”和“绝不”两类清单比如“必须按序号输出”和“绝不要编造数据”。这听上去机械但能帮你建立指令的边界感。另一个必练的是 few-shot 示例。好示例胜过长篇解释三个覆盖不同情况的输入输出对往往比一大段规则更有效。这阶段可以找一份公开的指令数据集每天改写三个实践样例重点是观察同一个提示词在不同输入下的稳定性而不是看单次成功案例。2.3 阶段二搞清楚代理的执行循环第二阶段最容易被人忽略但它决定你能不能写出“代理愿意执行”的技能。你需要理解一个基本事实代理不是直接把你的技能文本吞进肚子里然后立刻输出结果它有一个执行循环通常是“理解任务 → 调用可用资源 → 观察结果 → 再推理 → 再行动”。这意味着技能里的指令不只是在指导“最后输出”还在指导“中间每一步怎么做”。比如你想让代理处理一份 CSV 数据你需要明确告诉它哪些步骤需要它直接推理哪些步骤应该调用代码工具哪些情况需要停下来向用户确认。如果这些信息缺失代理就会自己脑补而脑补往往是错的。我自己的做法是在技能正文里画一条“执行路径”用编号列出每个关键决策点。代理在执行时会有更清晰的引导不会迷失在长文本里。核心原则是一次只让代理做一件事做完再做下一件事。想让代理分心去做多线程处理结果往往是一场灾难。2.4 阶段三掌握技能格式与加载机制进入第三阶段也就是“Skills 编写”的正题。虽然不同平台的技术细节有差异但主流思路都差不多一个技能通常包含名称、描述、指令正文、示例和附属资源。格式上头部信息用键值结构定义指令正文用段落描述示例则单独列出来。这个阶段你不需要写出完整的商业级技能目标只有一个跑通一个最小可用的技能。什么算最小可用我建议选一个“你每天都在做的事”比如写周报、整理帖子提纲把它做成技能。做完后你要能回答三个问题代理在什么条件下会加载这个技能加载后它做了什么输出结果能不能达到你人工验收的标准把这三件事跑通你对技能的系统理解会立刻变得具象。我已经看到太多人一上来就研究复杂格式却连最基本的“描述字段写得好不好”都没考虑这是最大的误区。2.5 阶段四从模仿到重构学会格式之后下一步是收集五个左右你觉得特别好的技能示例逐行拆解它们的写法。拆解时不用太关注业务逻辑重点关注三个点描述怎么写的、指令分几层组织、示例选了什么场景。模仿阶段我推荐一个特别有效的练习叫“脱壳重写”。把别人技能里的业务背景全部抽掉保留结构骨架然后套进你自己的真实场景里重新填内容。这样做的好处是你既不会陷入抄袭又能掌握优秀结构的精髓。我通过这个方法重构过七八次后来遇到新需求脑子里基本能自动生成一套结构框架。这里还有一条经验不要只模仿芯片行业的成功案例你所在的行业里哪怕是很小众的场景也值得做成技能。技能的价值由复用频率决定而不是由行业热门度决定。一个帮财务核对发票的冷门技能可能比一个帮所有人写文案的热门技能对你的实际收益更高。2.6 阶段五把测试和迭代当成重头戏如果说前几个阶段是“写技能”那第五阶段就是“养技能”。很多人写完技能就发布上架结果没过几天就发现输出质量飘忽不定于是对技能失去信心。问题往往不在于技能思路不对而在于没有建立测试集。建立一个迭代测试集选一场真实的输入输出样本至少准备十个以上。每个测试样本包含“原始输入”“期望输出特征”和“验收标准”。验收标准不能写得太含糊比如“输出要专业”要落成“不能出现空白字段”“每段必须有明确结论”“数据必须和原文一致”。每次修改技能指令后把整个测试集完整跑一遍。即使只改了一句话也要全量回归。这么做虽然看起来很笨但它是把技能从“偶尔好用”变成“稳定好用”的唯一路径。我在项目里靠这套方法把一个会议纪要技能的准确率从刚及格拉到稳定交付靠的不是灵感而是连续两周的回归迭代。2.7 阶段六发布、复用与长期维护最后一个阶段看起来跟技术关系不大其实特别关键。技能写完不是终点怎么组织、怎么复用、怎么维护决定了你的技能资产会不会腐烂。我建议给每个技能建一个独立的目录文件名里带上版本号和适用模型范围。技能说明的能力边界要写清楚别让使用者包括未来的你自己对技能产生错误预期。如果你有很多技能可以在索引文件里按场景分成几类例如“文本处理”“数据分析”“流程管理”方便查找。更重要的思维转变是技能也要定期淘汰和更新。大模型能力升级很快以前需要靠复杂指令纠正的行为换了个更强的模型之后可能不需要了。我大概每隔一两个月就会把高频使用技能从头审视一遍把已经用不上的约束删掉把新的踩坑经验补进去。这个习惯让我的技能库一直保持轻量也避免了“指令越写越长效果越来越差”的典型困境。3. 从需求到上线手写一个完整技能3.1 需求定义先想清楚“不做什么”理论说太多没用我拿自己最近做的一个“会议纪要整理”技能来走一遍完整流程。收需求时用户给我的原话是“帮我整理会议纪要输出要清晰”。这句话根本没法直接写进技能我花了半天跟需求方确认了三件事输入是什么形态输出要包含哪些模块遇到信息缺失怎么办后来定下来的输入是“会议录音的转写文本”输出要求包含会议主题、核心结论、待办事项、风险与遗留问题四个模块。重点边界也划清楚了不进行内容扩写不自动安排负责人缺失信息用“待确认”占位绝不编造。需求定义这一步花的时间至少占整个项目三分之一但恰恰是最值得的部分。定义“不做什么”比定义“做什么”更重要这跟你写系统需求文档是一个道理。边界越模糊模型越容易自由发挥输出的不确定性就会指数级上升。3.2 设计文件结构与加载方式一个完整的技能不会只有一个文件我的会议纪要技能按以下结构组织meeting_minutes/ ├── SKILL.md ├── references/ │ ├── output_template.md │ └── style_rules.md └── examples/ ├── case_01_input.txt ├── case_01_output.md ├── case_02_input.txt └── case_02_output.mdSKILL.md 是入口文件也是代理最先读取的部分。references 里放输出模板和风格规范但不放在入口文件里因为代理只有在真正产出会议纪要时才需要这些细节。如果全塞进 SKILL.md每次加载技能都会吃进大量上下文消耗不必要。examples 目录里面是完整测试样例。这里我用的是“一个输入对应一个输出”的成对文件测试时特别好用。你还可以把 case 文件进一步拓展成自动化测试脚本不过前期手动跑也够了。3.3 编写核心技能文件接下来是 SKILL.md 的核心内容。我把最关键的部分抽象出来你可以直接参考结构。--- name: meeting_minutes_writer description: 根据会议录音的转写文本生成结构化会议纪要。当用户提到“整理会议纪要”、“出会议记录”、“会议总结”时触发。 instructions: | 你是团队内部的会议纪要与文档助理。你的任务是将用户提供的会议转写文本整理成一份结构化、客观、可执行的会议纪要。 处理流程 1. 通读全文先识别会议主题、参与角色、讨论主线。忽略开场寒暄和口头语。 2. 提取核心结论每个议题下至少明确一条结论结论必须能在原文中找到依据。 3. 提取待办事项格式为“负责人 | 事项 | 截止时间”。原文无法推断负责人或时间时统一写“待确认”不得自行编造。 4. 识别风险与遗留问题包括未决争议、资源不足、依赖外部的事项等。 5. 按 references/output_template.md 中的模板输出输出为 Markdown 格式。 必须遵守 - 只基于用户提供的转写文本生成内容不补充任何外部知识。 - 如果转写文本存在明显语病或重复可以做轻度清洗但不能改变原意。 - 所有待办事项都必须可追溯到原文禁止自行添加新任务。 - 输出时不要出现“我建议”“根据我的经验”等主观表达。 examples: - input: | 好那我们开始。今天主要是对齐一下新版本的上线计划。张工说首页加载太慢初步判断是图片没有压缩。 李姐那边反馈测试环境周中可以准备好。还有一个问题是支付回调经常超时需要后端排查。 output: | ## 会议主题新版本上线计划对齐 ## 核心结论 - 确定新版本上线前需要处理首页加载性能问题和支付回调超时问题。 ## 待办事项 - 张工 | 完成图片压缩方案并落地 | 待确认 - 后端 | 排查支付回调超时原因 | 待确认 - 李姐 | 准备测试环境 | 周中 ## 风险与遗留问题 - 支付回调超时原因尚未定位存在延期风险。几个容易被忽略的细节说明一下。description 里的触发词一定要覆盖同义表达否则用户换个说法技能就不触发。我在测试时就发现“整理会议记录”不会触发“会议纪要”后来把触发条件改成“会议纪要、会议记录、会议总结、会议摘要”等关键词才解决。instructions 的“必须遵守”部分不是为了让模型听命令而是为了打压幻觉。尤其是“只基于提供的转写文本”这一条在实测中反复证明了它的价值。3.4 测试集与验收拒绝“看着能用”技能写出来后我先用三个用例做冒烟测试再准备七个测试用例覆盖不同情况一段特别长的转写、一段充满口头语的转写、一段关键词很少的转写、一段包含多个议题的转写、一段信息明显缺失的转写等。每跑完一个用例把输出和预期模板做对比记录偏差类型。最常见的问题是待办事项格式不统一有时是“负责人-事项-时间”有时是“事项负责人”后来我在指令里把格式用“竖线分隔”这个明确要求写死又补了一个正例和一个反例才算稳定下来。这里强烈不建议只做人工目测。目测容易产生“看起来不错”的错觉结果换一个输入就崩。我推荐做成一份简单的对比表每条用例、每次修改前后、是否通过验收全程留痕。我把这个表格跑了两周会议纪要技能的稳定度才真正达到可交付水平。4. 高概率踩坑清单4.1 技能加载失败描述写得像个谜语最典型的表现是用户明明提到了相关任务代理却完全没有调用技能而是自己按通用能力硬答。排查下来大部分原因是 description 写得太抽象或太窄。我见过有人写“这是一个关于整理内容的技能”这基本等于没写。解决思路是描述里必须包含三要素使用场景、输入对象、输出结果。正确的描述长这样“将用户提供的会议转写文本整理为结构化会议纪要。用户提到‘整理会议纪要’‘会议记录’时触发。”让代理只用一句简短描述就能判断“要不要用”这才是好描述。另外注意技能的命名空间是否冲突。如果你的项目里有两个技能都叫“整理”代理很可能随机选一个而不是按内容区分。命名尽量具体例如把“整理”改成“会议纪要整理”或“周报模板整理”。4.2 技能加载了但输出依旧跑偏这种问题最磨人。你确认技能已经加载指令写得很清楚可结果还是不对。我检查的顺序通常是先看是不是指令的结构出了问题再看示例是否太少最后考虑模型是不是太弱。指令结构问题核心是“每句话都平等没有优先级”。代理面对一百行同等权重的说明时容易迷失重点。我建议把最重要的一条约束放在最前面并且在“必须遵守”里再加一遍强调完事后再用一个反例来锁定行为。最容易被忽视的是“示例太少”。规则写得再精细也没有一个具体例子直观。如果你发现输出形态跟预期差很多别急着改指令先补两个高质量正例试试往往效果立竿见影。4.3 指令越写越长效果反而变差这是我们最容易犯的贪心错误。技能第一次有问题加一条规则第二次换个方向出问题又加一条规则。结果技能从两百字膨胀到两千字加载变慢输出变迟钝而且旧问题没解决新问题不断出现。核心教训是每加一条规则前先确认它是否真的不可替代。很多规则只是对某个单一样例的过度拟合把这个样例换掉规则就变成噪声。我的做法是先跑一轮测试集把所有偏差样本拿出来看共性。只在共性重复出现两次以上时才决定加规则。“写技能”和“做模型训练”在这一点上很像过度拟合训练集必然牺牲泛化能力。保持技能精简是长期维护最重要的动作。4.4 过度设计常见场景是明明只需要一个简单的文本格式化技能非要引入脚本调用外部 API或者把文件结构设计得无比复杂。结果不仅开发周期拉长而且每增加一个外部依赖就多一个不稳定因素。判断要不要做复杂设计我有个很朴实的标准最小方案能不能覆盖 80% 的日常场景如果能就先用最小方案跑起来等真实需求增长到证明有必要再加复杂度。这个原则帮我避免了很多无意义的工作量。4.5 技能过期模型升级后不吃老指令了这是一件反直觉的事模型变强了你的技能反而可能失灵。因为早期技能里的很多指令是在当时模型能力不足的情况下设计出来的比如要求模型“不要输出多余的解释”换成更强的新模型后它可能已经天然会这样做了你的指令反而限制了它发挥。所以技能不是写一次就能一劳永逸。我在使用某个功能时发现换新版本模型后之前的复杂指令导致输出变得机械生硬删掉一半冗余指令后效果立刻恢复正常。定期审视技能删掉不必要的约束是每个技能维护者的必修课。5. 常见问题速查表症状常见原因快速解法输入相关任务时代理不调用技能description 描述过于宽泛或触发词过少在描述里写清场景、输入、输出并扩充同义触发词输出格式与预期不一致缺少明确格式示例或模板放错位置在 examples 中附上完整正例并在指令中指明模板路径输出不忠实原文出现编造内容缺少“只基于输入禁止补充外部信息”的约束在“必须遵守”段落中强制加入反幻觉规则技能偶尔好用偶尔崩规则过多或过拟合单一样例精简指令建立 10 条以上测试集做回归验证同一类任务有两个技能都匹配技能命名和描述没有区分度给技能命名加上场景前缀描述里写清使用边界换新模型后效果下降旧指令限制过多模型行为已变化删减冗余约束重新跑测试集校准这张表是我平时排查问题的起点。遇到异常时不要急着大改技能先按表格判断症状属于哪一种再决定动手方向。多数问题往往只需要改一两个字段而不是推翻重写。我个人在实际操作中的体会是技能编写最难的从来不是技术格式而是能不能克制住“不断加规则”的冲动真正站在代理的视角去理解它会怎么读这份手册。每次写完一个技能我都逼自己回答一个问题如果一个新同事完全不认识我只看这份手册他能做出一模一样的产出吗如果答案存在犹豫那就说明技能还有打磨空间。最后再分享一个我最近一直在用的小技巧把每一个粗糙的需求先当成一条普通提示词去跑跑通之后把提示词里“属于业务经验”的部分抽出来再套进技能结构里。这样写出来的技能不是凭空设计的而是被真实需求验证过的成功率会高很多。希望你也能在动手写第一个技能时体会到把模糊需求变成稳定产出的成就感。它确实需要一些耐心但回报非常值得。