最近Skills这个词在AI应用开发圈子里热度越来越高我第一次看到这种方案时的第一反应是这不就是把提示词封装成插件吗后来真正动手做了一两个Skill才发现它和传统的提示词工程完全是两个量级的东西。它解决的不是让模型听懂话的问题而是让模型在特定任务上稳定输出高质量结果的问题。这篇文章我想把项目的核心思路、实操细节、踩坑记录都摊开来聊聊适合正在做Agent应用、想把大模型从什么都懂一点变成具体干活靠谱的开发者。1. Skills到底在解决什么问题先搞清楚它和Prompt的边界1.1 为什么大家突然都在聊Skills大模型本身是典型的通才你问它什么它都能接上几句但一旦到了垂直场景它的表现就飘忽不定同一个需求换个说法输出质量可能相差十万八千里。尤其是那些重复性很强的任务比如周报生成、会议纪要整理、数据分析报告、客户邮件回复每次都要在提示词里反复交代格式、流程、注意事项不仅繁琐而且效果很难稳定。Skills这个东西本质上就是把完成某一类任务的标准工作流固化成一套可复用、可共享、可测试的模块。你可以把它理解成给大模型配了一本标准作业手册模型遇到对应场景时会主动翻开这本手册按照里面定义的步骤、格式、规则去执行。这个思路并不复杂但它把过去散落在提示词里的经验真正变成了可以像代码一样管理的资产。在Agent应用越来越复杂的今天单靠一两句提示词已经扛不住完整的工作流了。Skills提供了一条结构化的路径把任务拆成判断、执行、校验、兜底几个环节让模型的行为变得可预期。我实际用了几个项目之后最大的感受是它不是让模型更聪明而是让模型在你的业务里更守规矩。1.2 Skills与提示词、Function Calling、插件的区别很多人刚接触Skills时会把它和Function Calling混为一谈或者觉得它就是换了个名字的Prompt。从我的实践经验来看它们解决的是不同层面的问题。方案核心思路适合场景典型缺陷普通Prompt一段描述性的文本指令单次交互、简单任务可复用性差、稳定性低、难以测试Function Calling定义函数签名让模型按需调用需要获取实时数据、操作系统接口只解决了调用什么不管后续对话流程与输出规范Agent Skills完整工作流 指令 示例 脚本 校验规则可复用、专业、流程化的重复性任务构建成本高需要持续测试和维护它们的核心差异在于Function Calling是把动作交给了模型比如查询天气、创建订单但动作做完之后怎么组织语言、怎么处理异常模型还是自由发挥。Skills则是把动作和动作之后的表达规范打包在一起它既告诉模型要做什么也告诉模型做到什么程度算合格。另外Skills也不是简单的Prompt模板拼接。一个完整的Skill可以包含脚本、示例、验证规则、参考资料甚至还有多语言版本。Prompt只是Skill的一个组成部分而不是全部。这个定位想清楚了后面设计Skill时才不会走偏。1.3 什么样的任务适合做成Skill我见过不少朋友一上来就想把所有东西都做成Skill结果维护成本比收益还高。实际上判断一个任务适不适合做成Skill可以从下面几个问题入手这个任务是不是高频重复的如果一周只出现一次写成Prompt就够了做成Skill反而增加维护负担。输出格式是不是相对固定比如周报、日报、工单回复、会议纪要这些都有比较稳定的结构非常适合。任务边界是不是清晰能不能用一两句话描述清楚什么时候该用、什么时候不该用你手上是不是积累了很多有效的工作经验比如一个好的分析师整理数据报告的步骤、一个资深HR写职位描述的技巧这些经验沉淀下来才有价值。不适合做成Skill的典型场景是那些完全开放式的创意任务比如帮我写一篇散文——没有固定流程没有标准输出格式Skill反而会限制模型的发挥空间。另外如果任务核心依赖实时数据应该优先考虑做成工具调用再配合Skill去做流程编排而不是把实时数据逻辑硬塞进Skill的静态指令里。这个边界感是设计Skill时最重要的第一步。2. 动手前必看Skill的结构与核心设计细节2.1 一个标准Skill的目录长什么样在实际落地时我通常会让每个Skill保持一个清晰的目录结构这样不仅方便测试也方便后续给团队其他人复用。下面是我常用的一个标准布局my-skill/ ├── SKILL.md ├── scripts/ │ ├── validate.py │ └── run.py ├── references/ │ ├── example-1.md │ └── example-2.md └── assets/ └── templates/SKILL.md是入口文件负责让模型理解这个Skill是干什么的、什么时候用、怎么执行它是最核心的部分。scripts目录放可执行的脚本用于格式化、校验、数据抓取等操作。references目录放示例和参考材料这些内容不一定会被模型完整读到但在需要时可以按需加载。assets目录放静态资源比如输出模板、图片等。这个结构的意义在于把指令和资源分开让模型只读必要的描述而把沉重的示例和模板放到外部需要用的时候再读。很多初版Skill写得冗长就是因为把所有东西都塞进了一个大提示词里既浪费上下文又容易让模型抓不住重点。目录结构的设计本质上就是在强制你做信息分层。2.2 元信息是命门description怎么写得又准又薄SKILL.md的头部通常包含一段元信息我用YAML格式比较多这段信息是模型判断该不该调用这个Skill的核心依据。如果description写得太空泛模型该触发时不触发写得太长又白白吃掉大量上下文额度。这里有个推荐的写法结构当【条件】时执行【任务】并输出【格式】。--- name: weekly-report description: 根据工作日志生成周报适用于周报汇总、进度汇报、项目复盘、本周工作整理 when_to_use: 当用户要求生成周报、整理本周进展、复盘项目进度、汇报工作结果时 version: 1.0.0 ---这段元信息看起来简单但有几个细节容易被忽略第一description里要写用户可能的自然表达比如整理一下这周做的事也应该触发周报Skill第二when_to_use要写清楚触发条件甚至可以加上反例避免和别的Skill混淆第三版本号一定要写方便后面迭代回溯。我在测试中发现同样的Skill把description从处理周报任务改成上面这种带场景描述的说法之后触发准确率有了非常明显的提升。另外一点元信息只负责触发判断不要在description里写详细的执行步骤。执行流程放正文触发描述放元信息职责分离模型才不容易乱。2.3 指令正文分层编写规则层、流程层、质量层进入SKILL.md的正文部分我习惯把指令拆成三个层次。第一层是规则层定义角色和底线比如你是项目经理助理不允许编造用户未提供的数据。第二层是流程层给出具体执行步骤比如先把日志拆分成项目维度再逐项目提取进展和风险。第三层是质量层定义输出标准和验收条件比如必须输出Markdown表格包含序号、项目名称、本周进展、风险问题、下周计划。分层写的最大好处是模型在执行过程中即使没有严格逐字跟读也能通过层级结构快速抓住逻辑不容易在中途跑偏。我自己早期写Skill的时候习惯于把所有要求混成一个自然段结果模型经常只执行了前两句后面全凭发挥。改成三个清晰层次之后指令遵循率明显上升尤其是流程层写得越细模型的执行就越稳。有个小技巧流程层不要超过六个步骤超过六步可以拆成主流程分支流程。模型在多步骤任务里容易遗忘前置步骤步骤越少记忆负担越轻。质量层一定要写什么算不合格比如风险问题必须写真实风险没有则写无不允许留空。这类否定性约束比肯定性约束更有效。2.4 脚本与安全边界Skill不只会说话还会动手很多Skill不仅仅包含文本指令还可以挂脚本。比如生成周报之后自动做一次Markdown格式校验或者把用户输入的数据自动结构化。有了脚本Skill就像长出了手能做的事一下子多了一个量级。但脚本也带来了安全风险这是很多人容易忽略的地方。我踩过的坑主要有三类第一脚本直接拼接用户输入存在命令注入风险第二脚本读取文件时没有做路径限制可能访问到不该访问的目录第三脚本没有设置超时和资源限制一旦失控会长时间占用计算资源。现在我在设计Skill脚本时会强制遵守几条铁律不允许把用户原始输入直接传入shell命令一律通过参数化方式传递读取文件必须限制在Skill自己的目录范围内所有脚本必须设置超时时间并在入口处捕获所有异常。看起来麻烦但能省掉无数个半夜被报警吵醒的瞬间。还有一点脚本不是必须的。如果任务本身只需要模型做文字整理就没必要硬挂一个脚本。每增加一个脚本就增加一个故障点。只有当脚本确实能带来确定性收益比如格式校验、数据转换时我才会引入。3. 从零做一个周报生成Skill完整实操记录3.1 需求定义与验收清单前面聊了那么多理论现在来看一个完整的实操例子。我选周报生成这个场景原因是它足够典型、足够高频而且几乎每个开发者都遇到过类似的痛点。需求定义如下输入是几段零散的工作日志输出是一份结构化的周报按项目维度汇总包含目标完成情况、本周进展、遇到的问题、下周计划。正式的验收清单有三条第一输出必须是Markdown表格包含序号、项目名称、本周进展、风险与问题、下周计划五列第二输入中明确提到的内容必须完整覆盖不允许遗漏第三对于用户没有提供的信息必须标注待补充或主动追问绝对禁止编造。这三条验收标准写SKILL.md和后续测试时都会反复用到所以在一开始就要定死。3.2 编写SKILL.md从元信息到执行流程下面是我实际使用的一个SKILL.md精简版本结构上完全可以复用--- name: weekly-report description: 根据工作日志生成周报适用于周报汇总、进度汇报、项目复盘、本周工作整理 when_to_use: 当用户要求生成周报、整理本周进展、复盘项目进度、汇报工作结果时 version: 1.0.0 --- # 周报生成 ## 角色 你是一名熟悉项目管理的助理负责将零散的工作日志整理为结构化周报。 ## 输入 - 用户提供的工作日志格式不限可以是列表、段落或散乱记录。 ## 执行流程 1. 将工作日志按项目名称拆分无法归类的条目归入“其他”项目。 2. 对每个项目提取四项信息目标完成情况、本周进展、遇到的问题、下周计划。 3. 用户未提到的内容统一标注“待补充”并写清楚缺少哪部分信息。 4. 汇总输出为Markdown表格包含序号、项目名称、本周进展、风险与问题、下周计划。 ## 输出格式 | 序号 | 项目名称 | 本周进展 | 风险与问题 | 下周计划 | | --- | --- | --- | --- | --- | | 1 | 某跨平台系统 | 完成登录模块联调 | 认证服务偶发超时 | 修复超时问题 | | 2 | 某图像处理Demo | 输出质量测试 | 无 | 补充边缘用例 | ## 注意事项 - 如果输入信息不足以生成任何一行直接告诉用户缺少哪些信息请用户补充后再生成。 - 不要编造用户没有提到过的项目或数据。 - 保持表格格式统一不要引入额外的内嵌列表。这份SKILL.md看起来不长但每一段都在承担职责角色定义限制了模型的语气和视角执行流程拆解了任务步骤输出格式给出了明确的模板注意事项兜住了最常见的错误。其中输出格式里的示例表格尤其重要模型在生成时会不自觉地去模仿这个格式所以示例质量直接决定输出质量。3.3 增加脚本做格式校验为了确保输出不会被模型自由发挥变成奇怪的格式我给这个Skill加了一个Python校验脚本。它的作用是读取模型生成的Markdown文本检查表格结构是否完整、列数是否一致、是否存在语法缺失。import sys import re def check_table(md_text: str) - list: issues [] lines md_text.strip().splitlines() header None in_table False for i, line in enumerate(lines): if line.strip().startswith(|): cols [c.strip() for c in line.strip().strip(|).split(|)] if not in_table: header cols in_table True elif re.match(r^\s*\|[\s:|-]\|\s*$, line): continue else: if len(cols) ! len(header): issues.append(f第{i1}行列数不一致{line}) else: in_table False return issues if __name__ __main__: md sys.stdin.read() issues check_table(md) if issues: print(校验不通过表格列数不一致) for issue in issues: print(issue) sys.exit(1) print(校验通过) sys.exit(0)这个脚本只做结构校验不做语义校验因为语义判断必须交给模型本身但结构问题完全可以用代码拦下来。在实际接入时可以让代理在模型生成完成后自动调用这个脚本失败就要求模型重新生成这样就形成了一道自动化的质量防线。脚本虽小但配合LLM的生成路径能让格式不稳定这个老大难问题大幅缓解。3.4 接入Agent、跑测试与回归SKILL.md和脚本都准备好了接下来就要把它挂到Agent框架里。我习惯把Skills目录配置到Agent的加载路径中让框架在初始化时自动读取所有Skill的元信息并把它们拼接到系统提示词里。这样模型在收到用户消息时就能根据description自动决定是否调用。接好之后一定要跑一组测试用例我建议至少覆盖三类触发测试、内容测试、边界测试。触发测试是输入帮我写个周报看能不能正确触发内容测试是给一段有明确项目信息的工作日志检查输出表格是否完整、信息是否准确边界测试是什么信息都不给直接要求生成周报看模型会不会追问而不是硬编。下面是我当时跑的一组合格记录测试类型输入示例预期结果实际结果触发测试帮我生成一下这周的周报调用weekly-report正常触发内容测试这周完成了A项目登录模块、修复了B项目三个bug表格里包含A项目和B项目两行两行均正确边界测试直接说写周报追问缺少哪些信息正确追问我建议把这组用例保存下来每次修改Skill之后都跑一遍防止改一个地方把另一个功能修坏了。这种回归测试的习惯是Skill从能用走向稳定的关键一步。4. 踩坑实录Skills落地的常见问题与排查思路4.1 模型不触发Skill总是泛泛回答怎么办这是最常遇到的问题而且特别让人恼火你明明已经把Skill写得清清楚楚模型就是不用。排查下来最常见的根因有三个。第一description和用户的自然表达差距太大。用户说帮我整理一下这周做的事情你的description里写的是生成周报模型可能根本没想到要调用。解法是把用户的可能表达写进description甚至可以铺开三四个近义说法。第二多个Skill的description有重叠模型产生混淆不知道选哪个。这时候需要给每个Skill添加when not to use的反面约束。比如会议纪要Skill里写当用户明确要求按周报格式输出时不要使用本技能可以大幅减少误触发。第三模型本身能力较弱做不到自动选择技能。这种情况下不要硬撑可以改成手动触发机制在用户输入里加斜杠命令比如/weekly让Skill通过路由规则直接加载。实战中我经常采用自动手动双通道既能照顾自然交互又能在关键时刻兜底。4.2 输出格式飘忽不定一会儿表格一会儿列表格式不稳定是Skills落地时最容易让人血压升高的一个问题。上一条生成的是完美表格换一个用户换个说法可能就变成了列表或者夹杂着一堆加粗文本。这个问题我通常从三方面下手第一输出格式区直接放一个必须复制的示例而且示例里不要出现任何多余的解释性文字第二在指令里加上否定性约束比如禁止输出表格以外的任何摘要性描述第三在生成后调用格式校验脚本失败就强制重新生成。还有一个容易被忽略的因素模型服务的temperature设置。temperature过高时即使指令写得很严格模型也会放飞自我。我在实际项目中凡是跑Skill的调用temperature一律降到0.2以下。这不算什么高深技巧但效果立竿见影输出稳定性肉眼可见地上升了。4.3 多个Skill互相干扰出现张冠李戴当项目里的Skill数量超过三四个之后新的问题就来了模型经常把A技能的执行方式套到B技能上。我遇到过最典型的一次有一个周报Skill和一个会议纪要Skill用户说把今天的会议内容整理成记录模型偶尔会调用会议纪要Skill但生成的格式却是周报表格因为它的系统提示词里同时加载了两个Skill执行时发生了混用。这个问题的解法第一是在每个Skill的元信息里写clear的职责边界尤其是不适用于什么场景第二是尽量让Skill之间的触发词不要重叠比如周报侧重每周、进展、计划会议纪要侧重会议、讨论、结论、待办事项第三给每个Skill的输出格式加一个独特的模板头比如会议纪要统一以# 会议纪要开头这样即使模型调用错了执行结果也能被测试脚本识别出来。这条经验是我踩了两次坑之后总结出来的现在多Skill协作时再也没出现过串场。4.4 上下文被Skill加载顶爆了怎么办Skill虽然好用但它不是免费的。每个Skill的description加上部分指令进入系统提示词都会占用上下文额度。如果你的系统里挂了十几个Skill光Skill描述可能就要吃掉两三千个Token留给真实对话的额度就变少了。控制上下文的策略我总结了四个第一description严格控制在一两百字内只保留触发判断必需信息第二SKILL.md里的references示例不要全部塞进提示词改成按需加载只有当模型判断需要参考时才读取对应文件第三按业务场景切分Skills集合比如客服场景加载客服相关技能研发场景加载研发相关技能不要做一个全量大杂烩第四定期检查Token消耗如果某个Skill的描述占据了过量上下文且触发率很低说明它设计得过于宽泛要么优化description要么直接下线。上下文额度是有限的Skill数量再多能用得上的才是资产用不上的全是负担。5. 从单体到体系Skills的评估与团队协作5.1 我用来判断Skill质量的5个指标做了一段时间Skills之后我意识到一个问题如果不能用数字评价Skill好坏后面就没办法持续优化。于是我在项目中总结了一套评估指标现在每次迭代都会用这套指标做一次体检。指标说明合格线触发准确率该触发时能触发不该触发时不触发90%以上指令遵循率是否按流程执行不跳步、不省略95%以上输出合格率输出格式、内容是否满足验收清单90%以上平均Token消耗每次调用占用的上下文与输出量越低越好迭代成本修改一个Skill平均需要多少时间0.5天以内要拿到这些指标光靠感觉不够需要搭一个简单的测试集把上面提到的触发测试、内容测试、边界测试写成固定用例每次改动Skill后跑一遍记录触发情况、输出合格情况和Token消耗。人工抽检也必不可少LLM的输出会有随机性固定测试集随机抽检双管齐下才能对Skill质量建立真实可信的认知。5.2 团队里如何维护Skills仓库当Skill在团队里积累到一定数量后就会形成技能库的雏形这时候最怕的就是脏乱差。我的习惯是给每个Skill加版本号、变更记录、负责人并且把测试用例和SKILL.md放在一起管理。新增一个Skill之前强制走一遍现有技能列表避免重复造轮子也避免两个Skill撞车。团队协作中还有一个容易被忽视的细节写Skill的人往往是资深开发者但读Skill的可能是新同学甚至可能是完全不懂业务的测试人员。所以SKILL.md的description和流程层一定要写得傻瓜化让不了解上下文的人看一眼就能判断这个Skill是干嘛的、什么时候会用。我见过一些非常强大的Skill但description写得像加密电报除了作者本人谁也看不懂这种Skill再强也发挥不了价值。把经验沉淀成谁都能读懂的规则才是Skills体系化建设的真正意义。最后说一点我自己的体会。把Agent从什么都会一点但什么都不稳定变成在固定任务上非常可靠Skills是我目前试下来成本最低的一条路。我最早也以为Skills只是提示词工程的换皮做了几个实际项目后才发现它真正的价值是逼着你把模糊的需求拆成可验收、可测试、可迭代的工序。如果你刚接触Skills别一上来就追求大而全先选一个你每周都要重复做的任务老老实实写一个最小可用版本把它接到实际流程里跑两周。踩过的坑多了你对Skills的理解自然就深了这个过程没人能替你走。