从提示词到技能封装：AI Agent开发中Skills的完整指南

这两年只要你在AI开发这个圈子里泡着几乎不可能没听过 skills 这个词。从年初开始各大AI平台和开源项目纷纷把 skills 作为核心能力单元推出来社区里铺天盖地都是“如何写好一个skill”的讨论。但如果你真去翻文档会发现大家讲的并不是同一件事有人把skill理解成一套提示词模板有人把它当成插件还有人直接拿它对标GPTs里的自定义指令。以我做Agent开发这几年的经验来看skills 确实不是一个能够一句话说清的概念。它既不是单纯的提示工程产物也不是传统意义上的代码插件它更像是介于两者之间的一套“可复用的能力封装单元”。这篇文章我就从实际项目出发把这个概念掰开揉碎讲清楚它解决什么问题、结构上应该怎么组织、实际开发一套skill要经过哪些步骤以及最容易踩的那些坑。不管你是刚接触这个概念的新手还是已经在写skills但总感觉差点意思的老手这篇都值得你看完。1. 为什么突然都在说skills从提示词到能力单元的演进1.1 先说清楚skills到底是个什么东西如果你拆开看这个单词本身它就是一个朴素的“技能”。但在AI Agent开发的语境里它有一套特定的含义。我自己的理解是一个skill就是把完成某一类任务所需的方法、步骤、约束条件和参考资源打包成一整套可被模型调用的结构化描述。这和普通提示词有什么区别区别就在“可被模型调用”这六个字上。普通的提示词是一段塞在系统prompt里的文字模型每次都在处理这段文字按其中的要求去执行。但skills不一样它拥有一定的“发现机制”——模型会先判断当前任务是否需要某个技能再加载对应的描述和内容来执行。说白了就是实现了一种按需加载把原本臃肿的系统提示词拆成了若干独立模块。这里有个特别重要的细节skills 的底层大多还是提示词但它已经是“有结构的提示词”。它的描述部分不是让人看的而是让模型看的——为了让它能够清楚地判断“什么时候该用这个技能、什么时候不该用”。这就决定了它的写法与普通提示词有本质差异。1.2 从Prompt、Plugin到Skills三代Agent扩展形式的对比我把这几年Agent外挂能力的典型形式做了个对比大家感受一下演进逻辑维度提示词Prompt插件Plugin技能Skills本质上是什么一段文字约束一段可执行代码结构化方法资源是否运行代码否是按需可含少量代码或纯文本复杂度极低高需要处理API接口、依赖等中等重逻辑轻工程修改成本直接改文字需要重新部署调试改文本或资源文件即可适合场景输出风格控制、通用规则外部系统深度交互特定领域方法论的复用可复用性不太行会污染主prompt强但有耦合成本强模块之间天然隔离从表格里能看出来插件的能力上限最高但开发和维护成本也高而且过度依赖API接口一旦外部环境变化就得跟着改。传统提示词便宜好用可你塞上十几个技能进去主prompt直接变成一本大杂烩模型反而抓不住重点。skills 正好卡在中间——它把“方法”和“实现”解耦描述怎么写、步骤怎么组织、参考资料用什么格式全部独立成文件按需加载。这种方式既规避了提示词堆积带来的注意力稀释问题又比插件轻得多。它要的不是更强大的执行能力而是更清晰的任务拆解与调用边界。1.3 一个实际场景从无到有学会写skill的思维切换我知道光说概念容易飘咱们拿一个特别常见的场景来看。假设我现在想做一个用于“客户投诉工单分类”的Agent以前用提示词的方式我会在系统prompt里写一大段“你是客服分类专家请按照以下步骤对工单进行分类……”然后把分类标准、举例、负面清单全部堆进去。结果就是这段描述动不动上千字模型执行简单任务时也被迫处理这些信息浪费token还容易在处理非工单任务时产生混乱。现在用skills的思路来设计做法完全不一样我先在主prompt里只留下一句话“当遇到客户投诉工单时调用 customer-complaint-triage 技能”然后我把具体的分类步骤、标准、输出规范全部写进这个skill对应的文件里。模型只在识别到工单分类需求时才会加载这套方法其他时候完全不受干扰。同样是完成一个任务设计思想的差异很大传统prompt是“把所有规则摆在台面上逼着模型遵守”skills是“把规则放在档案柜里需要时才取出来用”。这种思维切换才是学会写skills的第一步。2. skills的组成结构与设计原则2.1 一个标准skill的文件结构与核心文件拆解虽然不同平台的文件格式略有差异但主流的skills结构基本都包含三个核心部分SKILL.md 主文件、参考资源文件、以及可选的脚本文件。拿我之前做过的一个“竞品分析报告生成”skill来举例它的目录结构是这样的competitive-analysis/ ├── SKILL.md # 技能定义主文件 ├── reference/ # 参考资源目录 │ ├── report-template.md │ └── scoring-rubric.md └── scripts/ └── collect_mentions.py # 可选辅助脚本这里最重要的文件就是 SKILL.md。它是整个技能的入口和说明书。模型拿到这个文件后要能在最短时间内回答三个问题这个技能是做什么的什么情况下应该用它具体应该怎么一步步做所以SKILL.md本身要包含几个关键模块--- name: competitive-analysis description: 当用户需要分析竞争对手的产品定位、市场策略或功能对比时使用此技能。 --- # 竞品分析报告生成 ## 适用场景 - 用户给出竞品名称要求做对比分析 - 用户需要分析特定产品的市场定位 - 用户想了解竞品的定价策略 ## 不适用场景 - 用户只是想简单了解某个产品的功能不需要横向对比 - 用户没有指定竞品只泛泛地问“这个市场怎么样” ## 执行步骤 1. 确认用户想分析的竞品范围必要时追问澄清 2. 分析各个产品的核心定位与目标用户 3. 对比功能特性提炼差异点 4. 输出标准化的对比分析报告 ## 输出格式 参照 reference/report-template.md 中的模板输出注意几个细节description 要尽量写得“像模型会思考的话”因为它会被嵌入到模型的任务匹配过程中直接影响模型能否准确命中这个技能适用场景和不适用场景我建议都写因为对模型来说知道“什么时候不用”和知道“什么时候用”同样重要。2.2 描述越精准命中率越高怎么写好description很多人写skill的时候description总是写得很随意比如“用来分析竞品”。这种描述在技能库很小的时候可能还能凑合一旦技能数量涨到十几个甚至几十个模型匹配出错的概率会急剧上升。我总结了一个经验法则写description的时候对话对象不是用户而是模型的任务调度器。你要想象有一个调度模块在阅读这段文字判断“当前对话内容是否适合调用这个技能”。所以description里应该包含这几类语义信息触发场景用户会怎么表达这个需求核心任务对象分析的目标是什么预期产出技能最终会交付什么结果排除项哪些情况不该触发举一个对比案例。弱描述“用于竞品分析。”强描述“当用户给出具体产品名称或产品链接要求进行竞品对比、市场定位分析、功能差异拆解或定价策略研究时使用此技能。不适用于用户未指明具体竞品对象、仅询问行业宏观趋势的情况。”同一个技能前者可能被误用在泛泛的市场趋势问答上后者几乎不会误触发。这块值得多花时间打磨因为它直接决定了整个skills体系的精准度。2.3 设计准则单一职责、边界清晰、可独立验证在多个项目里折腾skills之后我总结出三条设计准则特别想分享出来。第一条是单一职责。一个skill只解决一个类型的问题。比如“撰写SEO文章”和“SEO关键词研究”最好拆成两个技能不要揉在一起。虽然模型能把两件事都做了但混在一起会让触发判断变得困难——用户只是想查几个关键词结果还得把整套文章写作逻辑加载进来。第二条是边界清晰。在SKILL.md里执行步骤写得越具体越好但不要越俎代庖去干扰其他技能的功能。我见过有人在一个“Python代码审查”的skill里写“如果发现性能问题请调用性能优化技能”。这种跨技能调用本身没错但如果你嵌得太硬会让整个逻辑变得脆弱——万一那个性能优化技能不存在或者改名了模型就会产生混乱。第三条是可独立验证。每个skill都应该是可以被单独测试的。这意味着它的输入是清晰的输出是明确的。你在开发完一个skill后至少要能造一个测试用例不用启动庞大的Agent系统直接在对话里验证它能不能被正确触发、步骤能不能顺利执行完。不能独立验证的技能出了问题都很难排查。3. 从零开发一个实用skill完整实操3.1 场景选择写一个真正有人用的“周报生成器”光说不练不行这一节咱们完整走一遍开发流程。我选一个大家都有共鸣的场景——周报生成。很多人觉得周报简单但真要让模型生成一份高质量周报其实比想象中复杂它需要理解用户一周的工作记录按项目维度归类提炼成果和问题最后按模板输出。如果只是写一段提示词让模型“帮我写周报”效果大概率不好。因为模型不知道你的周报要给谁看、要什么风格、需要覆盖哪些维度。而用skill来封装就可以把这些隐性要求变成显性步骤。我先梳理一下这个skill的需求文档输入用户本周的原始工作记录可以是一段流水账文字处理按项目/维度归类提炼关键成就与待解决问题输出符合企业模板的周报包含本周完成、问题与风险、下周计划三个板块附加要求语气简洁数据可量化不编造内容3.2 手写SKILL.md从描述到步骤逐字打磨有了需求文档就可以开始写SKILL.md了。这是整个过程的核心文件每一个模块都不能马虎。--- name: weekly-report-builder description: 当用户提供零散的工作记录或本周事项清单要求整理成周报、生成工作总结、提交周度汇报时使用此技能。不适用于撰写月报、年报或项目验收报告。 --- # 周报生成器 ## 适用场景 - 用户发来一堆工作流水账要求整理成周报格式 - 用户说“帮我写本周工作总结” - 用户给出几点工作内容希望按时间或项目维度归类 ## 不适用场景 - 周报中需要包含精确的财务数字或保密数据但用户未提供 - 用户要求的实际是日报生成 ## 执行步骤 1. 阅读用户提供的原始工作记录提取所有有效工作事项。 2. 对工作事项进行归类 - 按项目维度归类如产品迭代、客户支持、内部优化 - 对每类事项提炼核心成就要点 3. 识别“成果”和“风险”成果有可量化的数据要保留数据风险指阻碍进度的事项需要明示。 4. 按照模板输出周报格式参照下节“输出格式”。 5. 输出前检查不虚构未提供的数据不确定的信息用“待确认”标注。 ## 输出格式 ### 本周完成 - xxx项目完成xx功能上线协作xx部门完成联调 ### 问题与风险 - 待确认xx需求变更影响排期 ### 下周计划 - xxx项目推进xx模块开发预计xx完成这个文件的关键在于步骤编号。模型在执行时对编号的敏感度很高步骤越清晰输出越稳定。我在第2步用了“归类”而不是简单写“整理”因为归类包含了一层分析逻辑模型会主动去做语义聚合。在第5步加了检查项这是很多prompt里没有的——显式的质量检查文字能明显降低模型胡编乱造的概率。3.3 添加参考资源模板与示例让输出格式稳定下来光有SKILL.md还不够模型在生成周报时如果没有具体格式参照很容易发挥出各种“自由风格”。这时就需要添加参考资源文件。我把模板和示例放在 reference 目录下# 周报模板 ## 本周完成 | 项目 | 成果描述 | 量化指标 | | ---- | ---- | ---- | | 示例项目 | 完成核心模块开发 | 接口响应时间降低20% | ## 问题与风险 - 风险描述影响范围/当前状态/需要的支持 ## 下周计划 1. 项目A目标描述预计完成节点 2. 项目B目标描述预计完成节点参考资源的作用是给模型一个“格式锚点”。经验表明模型在输出结构化内容时提供一个具体的格式范本比在步骤里描述十句“要清晰地排版”都要有效。这个文件不用写得多花哨关键是让模型一眼就明白最终交付物长什么样。3.4 测试用例与调试10分钟快速验证skill可用性文件写完之后最重要的环节是测试。我自己习惯在开发环境里用一个极简的对话流来测试每个skill不启动完整系统直接模拟调用逻辑。测试的过程很简单就是造几个输入看模型能不能正确触发和输出。我当时的测试用例有三组第一组是正常输入“这周我完成了登录模块重构配合测试同学做了三轮回归修复了5个bug另外在准备下周的版本发布。”第二组是边缘输入“我这几天的任务就是开会、回邮件、整理文档。”第三组是负向输入“帮我写一下这个项目的验收报告。”第一组测试看的是执行质量输出中是否包含归类、量化数据是否保留第二组看的是当输入内容很“薄”时模型能不能套用模板输出一份合理的周报而不是强行编造数据第三组看的是技能边界它应该拒绝执行或提示用户使用其他技能。前两组一次通过第三组出现了一点问题——模型并没有识别出“项目验收报告”不属于周报范畴仍然调用了技能。我后来在description里加了一句“不适用于项目验收报告”问题就解决了。4. 调试、评估与常见的坑4.1 现象一技能总是不被触发问题出在哪这是我在技能数量变多之后遇到的最频繁的问题。你写了一个技能但不管怎么对话模型就跟没看见一样就是不调用。排查下来原因八成在 description 上。第一个问题是描述过长超过了模型调度的注意力窗口。模型在每轮对话中会扫描所有技能的description如果你的描述超过三四句话后半部分很可能不会被仔细阅读。第二个问题是描述里的关键词和用户真实表达差得太远。比如你写的是“自动生成竞品差异分析矩阵”用户说的是“帮我看看他俩家产品有啥不一样”如果描述里没有“对比”“区别”“不一样”这类口语化词汇模型就匹配不上。我的建议是description里至少要被触发场景引导词覆盖到三到五种不同说法包括口语化表达。写完以后自己念一遍想象一下用户会用什么样的自然语言触发这个技能然后把那些语言写进去。4.2 现象二调用成功了但输出完全不符合预期另一种常见情况是模型确实调用了技能但输出结果跟你想的相差十万八千里。这种问题多数出在SKILL.md内部的执行步骤不够详实或者你对输出格式没有给出硬性约束。我之前写过一个“数据清洗”技能SKILL.md里只写了“清洗数据包括去重、处理缺失值、修正格式”。结果模型拿到数据后只做了一步去重就停了缺失值完全没处理。后来我在步骤里加得非常具体“第2步逐列检查数据列出每列的缺失值比例第3步对缺失值超过30%的列标记为建议剔除第4步对缺失值低于30%的列按要求填充……”。加了这些以后输出质量立刻上来了。这里有一个通用原则把“怎么做”拆得越细模型执行的稳定性越高。每个步骤都应该是一个可以验证的动作而不是一个抽象的描述。4.3 现象三技能之间互相打架触发错乱当技能库越来越大不同技能的description可能包含相似的触发场景这时候模型就容易犯迷糊。我遇到过一个经典案例我同时有“会议纪要整理”和“任务拆解”两个技能用户输入“帮我把这个会议里提到的任务整理一下”两个技能都被触发了输出结果混杂在一起乱得没法看。解决这个问题一是在描述里写清楚互斥条件。会议纪要整理的description加上“不适用于需要将任务进一步拆解到个人维度的场景”任务拆解的description加上“不适用于仅需要整理会议记录的场景”。二是给技能设置优先级当模型判断两个技能都可调用时默认选择优先级高的那个。如果你的平台不支持优先级配置那你至少要确保每个skill的“不适用场景”写得足够清晰从源头减少误触发的可能。5. 如何管理一个日渐增多的skills库5.1 命名规范与目录组织从第一天就不要偷懒技能数量少的时候随便起名无所谓。但你一旦写了二十个技能没有一个统一规范的话后面维护就是一场灾难。我的规范是这样的目录名使用 kebab-case短横线分隔如weekly-report-builder每个技能目录下必须有 SKILL.md文件名统一不搞变体参考资源统一放reference/目录脚本统一放scripts/每个技能的 description 不超过50个中文字符方便模型调度扫描在SKILL.md顶部添加version字段方便版本追踪5.2 版本管理与变更记录技能也是要迭代的很多人把skills当成一次性写死的文件改完就完事。但真实使用中技能需要持续迭代模型版本升级后响应模式会变业务需求变化后步骤要调整。如果不做版本管理你根本不知道当前这个技能是哪一版改出来的坏了都没法回滚。我在每个skill目录下放了一个CHANGELOG.md记录每次修改的日期、改动内容和原因。别小看这个习惯对一个长期维护的Agent系统来说技能库的稳定性往往取决于这些不起眼的管理细节。5.3 技能间的依赖关系少用隐式耦合还有一个管理上的坑是技能间的隐式依赖。比如你的“周报生成器”技能里暗示了“如果用户给了数据可以调用数据可视化技能生成图表”但你又没有在文件里明确声明这个依赖。结果某一天你把数据可视化技能改名了周报生成器就开始出问题而你排查半天才发现在这个隐藏关联上。所以我的建议是技能间的调用关系要么直接写在步骤里并用明确的名字引用要么就不要依赖。隐式耦合是系统设计里最隐蔽的敌人。宁可牺牲一点灵活性也要保证每个技能相对独立这样整个库的可维护性才会高。5.4 如何评估一个技能写得好不好三个维度最后聊一下怎么衡量一个skilled的质量。我在长期使用中总结出三个评估维度触发准确率、执行稳定性和输出复用率。评估维度评估方法通过标准触发准确率准备20条典型与非典型输入测试是否能正确触发/不触发误触发率低于10%执行稳定性同一输入执行5次对比输出结构的差异结构一致无关键字段遗漏输出复用率生成的结果是否需要大量人工修改直接可用率超过70%这三个维度比“看起来写得规不规范”更能反映一个技能的真实水平。我建议每写完一个skill都拿这组标准过一遍有问题的该调就调不要拖。关于skills我其实一直有个感受很多人觉得这是技术问题是提示词工程的一种变体但我更倾向于认为它本质上是一种“知识结构化”的问题。你把一个领域的操作方法整理得足够清晰让模型能够在正确的时机调用它这背后考验的是你对任务本身的理解深度。写skill的过程最能逼你把自己脑子里模糊的经验梳理成清晰的步骤这本身就有很大的价值。如果你准备开始写第一个skill我建议从你最常做的重复性事务开始把它完整的思考过程、判断标准和输出模板都写下来然后封装成一个技能。用起来以后你会发现原本需要反复交代给AI的事情一次就能到位。