最近这段时间我一直在折腾智能体相关的项目，翻了不少开源仓库，发现一个词出现的频率越来越高：skills。不管是刚入门的还是做了很久的，大家都在聊怎么把零散提示词整理成技能包。这个趋势有点意思——以前我们习惯把背景、规则、示例一股脑塞进系统提示词里，结果提示词越来越长，维护越来越痛苦；现在主流Agent产品普遍支持按需加载的技能目录，也就是把一份说明书加配套示例放进独立目录，需要时自动调用。这篇东西我结合自己踩过的坑，聊聊skills到底是什么、一个技能包怎么设计、以及一套可以直接抄走的实操流程。适合正在做Agent应用、想优化提示词管理方式、或者准备把个人经验沉淀成可复用资产的人。
1. 为什么突然到处都是“skills”：一次提示词工程的范式转移
1.1 从“塞进上下文”到“按需加载”
如果你接触过早期的智能体应用，一定经历过这样的场景：为了让它输出某种固定格式的内容，需要在系统提示词里写上大段描述，再把几个示例粘进去，最后还要补充一堆“不要……”的负面约束。一开始还好，但随着任务变多，问题就来了。
我这个月在维护一个内部用的报告生成助手时深有体会。刚开始只有周报、日报、月报三种模板，系统提示词一共两千字，还能接受。后来加了活动方案、复盘总结、竞品分析，提示词直接到了八千字。每一次对话都要把这些内容完整加载一遍，响应变慢不说，最要命的是任务之间开始互相干扰——明明是在写月报，却冒出一段活动方案的措辞风格。
skills解决的就是这个问题。它把原来必须常驻在提示词里的内容，拆成一个个独立的、按需加载的模块。用一个类比就很好懂：以前是在每个文件里粘贴一份工具函数，现在是把工具函数写进公共库，谁要用了再import一下。
这种范式转移带来的好处不仅仅是字面上“节省了上下文空间”，而是整个提示词的架构方式发生了变化。原来是一条巨大的、所有规则混在一起的“面条代码”，现在变成了一个个边界清晰、职责单一的“模块”。
1.2 为什么会在这个时间点集中爆发
这个时间点集中出现这个词，背后有实打实的技术推动力。一方面，上下文窗口虽然一直在扩大，但token的性价比决定了没有人愿意为每次请求支付不必要的开销；另一方面，Agent类应用开始承担更复杂的任务，它需要在不同任务之间快速切换能力。如果所有能力都堆在一个系统提示词里，不仅切换效率低，还容易让模型“精神分裂”。
另一个重要因素是框架层的成熟。现在不少Agent框架都内置了“技能目录”机制，约定好目录结构和描述格式，模型自己就会去查找该用的工具。这个机制一旦标准化，社区的分享成本就大幅降低了。你写好一个技能包，别人同样目录一放就能用，和当年npm生态起来的逻辑是一样的。
1.3 什么场景才真正需要技能包
先给个明确的结论：不是所有场景都需要把它做成技能包。
我这段时间的体会是，满足下面任意一条才值得：
- 同样的任务会反复执行，并且每次执行的背景知识是稳定的。
- 任务有明确的步骤流程，并且步骤之间存在固定顺序。
- 输出的格式、语气、内容范围有强约束，需要稳定的复现。
反过来，如果是一次性的问题、随口的问答、或者规则本身还在频繁变化的内容，直接写在对话里反而更灵活。强行做成技能包只会给你的维护清单增加负担。
| 对比维度 | 一次性提示词 | 技能包 |
|---|---|---|
| 上下文占用 | 每次完整加载 | 命中时才加载 |
| 维护成本 | 改一处要翻整个提示词 | 独立文件，改单个模块 |
| 任务隔离 | 容易互相污染 | 边界清晰 |
| 复用性 | 复制粘贴 | 多人、多项目共享 |
| 学习成本 | 零 | 需要理解约定和结构 |
2. 一个标准技能包长什么样：以SKILL.md为中心的文件结构
2.1 目录结构和核心文件
虽然不是所有框架都完全一致，但目前主流的Agent技能约定已经形成了一套事实标准：一个技能包就是一个独立的文件夹，放在固定的技能根目录下。文件夹里最重要的是一份技能说明文件，一般就约定成SKILL.md这个名字。
一个典型的技能包目录长这样：
@技能根目录/ └── 技能名称/ ├── SKILL.md ├── 参考资料/ │ └── 示例模板.md └── scripts/ └── parse.py这里要注意几点：技能文件夹的命名就是技能的名字，所以语义要清晰，最好能做到“看到名字就知道是什么领域”。SKILL.md是智能体判断“要不要用这个技能”的关键入口，它的描述写得好不好，直接决定了技能能不能在合适的时机被调用。参考资料的目录不是必须的，但对于需要大量示例支撑的任务，单独放一个目录比全部塞进说明文件干净得多。scripts目录是可选的，当技能里确实需要执行代码逻辑时才会用到。
2.2 SKILL.md 的固定格式
以我见过的大多数实现来说，SKILL.md由两块内容组成：YAML格式的元信息加正文。
元信息部分是整个技能包的“门面”，必须包含技能名称和描述。智能体拿到用户当前的问题后，会先用描述去匹配。描述写得越精确，匹配的准确率越高。这里多说一句，很多初写者犯的毛病是描述写得太泛，比如“适用于所有工作汇报”。这种等于没写，因为任何和汇报沾边的问题它都可能命中，结果就是频繁出现误调用。
正文部分才是技能真正发挥作用的地方。它需要做到三点：说清楚技能的边界、给出可执行的步骤、提供具体的示例。边界意味着要写明“本技能不适用于哪些情况”，这个很关键，能在匹配阶段帮智能体排除干扰。步骤要尽量拆细，每一句话都指向明确动作，避免模糊表述。示例是最有说服力的，正反例结合效果最好。
2.3 动手写一个最小可用的技能包
直接用我实际在用的一个技能举例，你看了就能抄。
这个技能解决的是周报生成问题。我们团队对周报格式有严格要求，原来每次写周报都要在对话框里重新贴一遍格式要求，后来我做成了技能包：
--- name: 周报生成 description: 当用户要求生成周报、整理一周边工作内容时使用。适用于以“周报”或“本周工作”为核心意图的请求，不适用于月报和项目复盘。 --- # 周报生成技能 ## 任务目标 将用户提供的一周工作碎片信息，整理为一篇结构清晰、重点突出的周报。 ## 操作步骤 1. 提取用户提供的工作事项，去掉口语化表达。 2. 按「完成的事」「进行中的事」「关键风险」「下周计划」四个维度归类。 3. 对每一类事项使用精确动词开头，例如“完成”“推动”“主导”“协调”。 4. 输出固定模板，控制在500字以内。 5. 如果没有提供关键风险，不要在周报中强行编造，留空即可。 ## 输出模板 ### 完成的事 - 事项描述（量化结果） ### 进行中的事 - 事项描述（当前进度） ### 关键风险 - 风险描述 ### 下周计划 - 计划事项 ## 示例 用户输入：“这周我把用户注册模块重构完了，还跟运营对了一下新版本时间线，另外客服那边反映有个退单问题还在查，下周准备开始做优惠券功能。” 输出： ### 完成的事 - 完成用户注册模块重构，接口响应时间下降40%。 ### 进行中的事 - 与运营团队确定新版本上线时间线。 ### 关键风险 - 客服反馈的退单问题仍在排查中，原因未定位。 ### 下周计划 - 启动优惠券功能开发。这个技能包我用下来命中率很高，核心在于两件事：description里明确了“本技能不适用于月报和项目复盘”，直接排除了大量误调用；正文里的示例提供了很强的输出参照，模型基本不需要发挥，照着模板走就行。
3. 三种典型封装思路：从需求出发设计你的技能包
3.1 固定输出格式类：把风格规范沉淀成技能
这类技能包的目标最单纯：在输出层面保持一致。比如产品需求文档、PRD、结案报告、学术摘要，都有固定的格式和语气要求。
我做过一个PRD生成的技能包，效果相当理想。它的核心不是列出步骤，而是写清楚产品文档的语言规范：需求背景必须从用户痛点展开、验收标准必须写“怎么测才算通过”、改动范围要明确到页面和接口级别。规范之外再给一个标准PRD的骨架模板，模型照着填内容就够了。
这类技能包最容易犯的错是把格式写得太死，连段落长短都要限制。模型为了满足你的字符数要求，反而会把内容写得很僵。正确做法是约束结构、约束语气、约束必要元素，但给正文表达留空间。
3.2 领域规则类：把检查清单变成可执行约束
领域规则类技能通常用于审查、校验、合规检查这类任务。核心思路是把人脑里的检查清单，翻译成模型能理解并执行的判断标准。
举个例子，我在另一个项目里做了一个“前端可访问性审查”的技能包。过去让模型做审查，它只会泛泛地说“颜色对比度可能不够”“建议增加alt属性”，没有判断依据。后期我把规则细化到了具体的数值和场景：
## 审查规则 1. 文本与背景的对比度比例不得低于4.5:1，大号文本不低于3:1。 2. 所有图片必须有alt文本，且不能使用“图片”“示意图”这类无意义描述。 3. 可点击元素的点击区域不得小于24x24像素。 4. 表单元素必须有关联的label标签。 5. 任何通过颜色单独传达的信息，必须有非颜色的辅助标识。这类技能的关键在于“规则是可验证的”。对比度比例、点击区域尺寸都是客观数值，模型输出结果之后人能快速复核。这个设计原则值得记住：能让机器验证的规则，就不要写主观描述。
3.3 流程编排类：把多步操作固化成标准动作
有些任务不是单次输出，而是一套流程。比如数据分析、文案生产流程、竞品调研、活动复盘，这类任务的特点是步骤之间互相依赖，前一步的结果会影响后一步的操作。
这时候技能包的职责就是变成一套“脚本”，告诉模型每一步干什么、每一步的输出要交给下一步怎么用。我写过一个“竞品分析调研”的技能包，第一层先要求模型列出需要调研的产品功能、目标用户、商业模式，第二层针对每个维度检索信息，第三层做横向对比、输出分析结论。每一步的输出格式都有约定，最后汇总时不会因为信息格式不统一而错位。
写流程类技能的最大心得是：给模型留出“边界内自主决策”的空间。比如在调研竞品维度时，让模型自己判断该关注哪些信息，不要把所有可能性都枚举出来。否则只要更新一次竞品，技能包就要重写一遍。
4. 实操全流程：把零散经验做成可复用技能包的完整记录
4.1 从痛点出发，先别急着写文件
我在前面的基础上，把你打开编辑器之前的准备工作也说透。很多人上手就闷头写SKILL.md，结果写完发现不是不好用，而是压根没被调用过。
我的建议是先做一个简单的成本收益分析。把这个技能包预计要承载的任务量估一下：每个月执行多少次？每次手工整理或提示词改写要花多少分钟？有没有完全可预测的格式规范？如果三个答不上来，很可能这个需求不值得做成技能包。经验之谈，真正值得的技能需求，一定是“高频、稳定、有明确边界”的。
拿刚才说的可访问性审查举例。我最初只想让模型快速帮我过一遍前端页面代码，属于明显的低频需求。但细想之后发现，团队每个迭代都要做一次审查，规则固定不变，输出格式也要统一归档。这才是真正值得做技能包的理由。
4.2 结构六步法，我反复用的套路
具体操作时我习惯分成六步，每一步都不省。老手可能觉得有些步骤多余，但新手严格跟一遍能少踩很多坑。
第一步，收集真实需求样本。把你过去三次到五次完成同一类任务的对话记录、输出结果全部找出来。这一步很多人忽略，但它决定了技能包的内容能不能覆盖真实使用场景，而不是凭想象写规则。
第二步，找出重复出现的模式。逐条看样本里哪些内容是稳定重复的：格式、措辞、顺序、必须包含的信息点。以周报为例，必然出现的段落永远是“完成的事”“进行中的事”“关键风险”“下周计划”。这些稳定结构就是技能包的骨架。
第三步，明确边界和常见误区。哪些情况下不要用这个技能？最容易做错的是什么？比如周报技能如果被用户拿去写项目复盘，就会出大问题。把边界直接写进元信息里，是最省事的规避方式。
第四步，起草SKILL.md。起草阶段遵循一个原则：能用客观语言描述的，就不要用主观语言。不是“注意语言要专业”，而是“禁止使用口头语缩写和网络用语”；不是“内容要简洁”，而是“总字数控制在500字以内”。客观且有数值边界的指令，模型的完成度显著更高。
第五步，准备正反例。单一的正例只会让模型照着临摹，再加一个反例才能帮助模型理解为什么不能那样写。反例最好是从真实失败记录里提取的，这样的“教训”最有说服力。
第六步，反复试跑和迭代。第一次运行几乎肯定不符合预期，不要慌。每次不符合预期的输出，先判断是规则没写清还是示例不到位，对应调整。通常在三轮调整之后能稳定下来。
4.3 一次完整的技能包制作现场
用“小程序页面备注文案风格审查”举例。项目里有个痛点：不同人写的备注文案风格差异很大，有的一行写完，有的长篇大论，阅读体验差。
我先收集了十个不同版本的备注文案，好坏各半。接着标注出优质文案的共性：以动词开头、明确说明当前状态、标记负责人和截止时间、语气中性。接着标注出问题文案的共性：纯口语化表达、包含个人情绪、指责他人、没有信息量。
最终写出的核心部分长这样：
--- name: 备注文案风格审查 description: 当用户要求审查或修改任务备注、工作日志中的备注内容时使用。必须包含原文或原文列表。仅适用于备注文案，不适用于正式文档。 --- # 备注文案风格审查技能 ## 执行步骤 1. 将用户提供的备注拆分，一条一条独立审查。 2. 对每条备注按下列标准评价，输出「通过」或「需要修改」及原因。 3. 对需要修改的备注，给出改写后的版本，与原文并列展示。 ## 审查标准 - 必须以明确动词开头（如“完成”“跟进”“修复”）。 - 必须包含状态信息：已完成、进行中、待处理、已暂停。 - 必须包含任务责任人，不允许出现“大家”“相关人员”这样的模糊主体。 - 语气必须中性，禁止出现指责性或情绪化表达。 - 紧急事项必须明确标记截止时间。 ## 示例对比 原文：「改完了，业务那边人还没回我，也不知道行不行」 修改后：「已完成需求方案修改，待业务方回复确认，预计本周五前同步结论」 原文：「这个页面卡死了，怎么一直没人管」 修改后：「进行中：列表页在低端机型出现卡顿，正在定位具体原因，一手负责人：某开发者，预计明天修复」制作过程中我发现，最有效的部分其实是示例对比。模型从抽象规则里学到的远不如从正反例里学到的多。如果你时间有限，优先保证示例的质量，规则部分能说清楚大方向就行。
5. 避坑记录与常见问题速查
5.1 为什么技能包总是没被调用
这是我在社区里看到最高频的问题。明明写好了技能，智能体就是不调用。排查顺序按下面这三步走，大部分问题能解决。
先查description是否准确。这是最常见的死因。描述写得模糊、宽泛，或者和用户当前任务的表达方式不一致，匹配就会失败。我遇到过一个个例，写了一个“高情商回复”技能，description里写的是“提供沟通建议和话术优化”，但用户真正触发的时候说的是“帮我看看这段消息该怎么说”。两边用词完全不同，自然就匹配不上。解决思路是描述里多放几种常见说法作为触发词。
再查技能包的数量和顺序。有些框架下能同时加载的技能数量有限，如果技能包里已经有几十个技能，新的技能很容易被挤掉。建议做一次技能瘦身，不常用的合并同类项，只保留高频率使用的技能。
最后查调用的优先级逻辑。有些框架里，通用技能和特定技能的优先级不同。特定技能反而排在后面，导致通用技能先接单。遇到这种情况，把特定技能的description里加上“优先于通用方案”的说明会有帮助。
5.2 为什么输出了但风格还是不稳定
技能被正常调用了，但输出风格时好时坏。这种情况十有八九是示例样本数量不够或者规则太抽象。
经验数据是：每个技能至少准备两个正例、一个反例。如果能准备三正两反，稳定性会有明显提升。不要嫌示例占字符数，它对输出的约束力远比几百字规则说明强。
另外找一个容易被忽视的细节：正例之间要有差异。如果两个正例都是同一类型，模型只会学习到那个类型的输出模式，换个场景又不会了。比如备注文案审查，正例要覆盖不同长度、不同状态类型、不同紧急程度，这样模型学到的才是“规则本身”而非“某个具体样本”。
5.3 一个技能包维护的长期成本问题
任何技能包都有有效期。业务规则变了、输出格式变了、数据指标变了，技能包就得跟着改。维护阶段最重要的动作是建立迭代日志。
我自己维护技能包的习惯是：每遇到一次不符合预期的输出，不着急改正文，而是先在技能包所在的文件夹里记录一行“日期+问题+猜测原因”。累积到三条以上记录再统一调整。这样能避免为了单个偶发case频繁改动规则，导致其他场景被破坏。
注意：技能包的改动一定要小步提交。千万不要一次改五处，然后测试发现更糟了，都不知道是哪处改坏了。
5.4 常见问题速查表
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 技能完全没被调用 | description表达和用户话语不匹配 | 在description中补充多种触发说法 |
| 技能偶尔不被调用 | 框架可加载技能数达到上限 | 精简技能包数量，合并同类项 |
| 输出格式部分符合预期 | 示例不够，或规则太抽象 | 增加差异化示例，规则具体化 |
| 输出风格前后不一致 | 正例之间差异太小 | 让正例覆盖更多子场景 |
| 某个技能影响其他任务 | 边界描述缺失 | 在description中写明“不适用”范围 |
| 修改后效果反而更差 | 一次改动太多 | 回滚到上一版本，逐条验证改动 |
结尾：一次真实使用体验收尾
我自己做了二十多个技能包之后，最大的感受是：技能包的意义不在于“把提示词写得更长更全”，而在于把你最稳定的那一部分工作方式固化下来。就像程序员不会每次都重新手写一个排序算法，而是调工具函数一样。技能包本质上是在帮你积累可复用的大脑模块。
最后分享一个我踩了挺多次坑才养成的习惯：每次完成一轮技能迭代，我都刻意用同一个任务跑一遍旧版和新版，对比输出差异。这比凭感觉改规则可靠得多。另外，技能包之间不要共享混乱的全局前缀，把“不适用范围”写清楚，会让智能体的调度像一个训练有素的助手，而不是一个什么都插一脚的万能工具箱。你做的技能包越精确，跑起来就越省心。
