最近我在整理手头的Agent项目时发现团队里讨论最多的词已经从Prompt悄悄变成了Skills。一开始我以为又是哪个新概念来凑热闹直到自己花了两周把几个高频重复的流程改写成技能包之后才意识到这玩意儿确实值得好好聊一聊。所谓Skills通俗点说就是给大模型准备的一套岗位作业指导书。过去我们写提示词恨不得一次写出一篇小作文把背景、规则、示例全塞进去用完一次就丢下次再复制一份改一改。Skills的思路完全不同它把完成一类任务所需的描述、步骤、参考范例、甚至可执行脚本打包成一个独立的文件夹让Agent在遇到对应需求时自动调用真正实现了能力沉淀和复用。这篇文章我打算从为什么要搞Skills、怎么设计一套技能包、到完整手写一个实战案例、再把我踩过的坑和排查思路整理一遍适合所有已经开始接触Agent、或正准备把提示词升级成标准化方案的朋友。看完你就能照着搭一套自己的技能库而不是继续当提示词临时工。1. 为什么突然都在聊Skills先搞清楚它在解决什么问题1.1 从提示词到技能包的进化逻辑大模型刚火起来那阵子大家都把Prompt当咒语觉得只要措辞得当模型就能开挂。实际上用过一段时间就会明显感觉到提示词的本质是一次性用品你费了很大力气写出一段让模型好好整理会议纪要的指令下一次换个人、换个场景可能又得从头调。我自己的转折点是在处理一堆重复性任务时发生的。那段时间每周要写项目周报、整理客户反馈、生成SQL查询每类任务的流程都差不多但每次都重新写提示词不仅浪费时间而且输出质量很不稳定。同一个需求今天让模型输出的格式和昨天就有出入更别提偶尔回复着回复着就跑偏了。Skills解决的就是这个问题。它把如何完成某类任务的整体方案固化下来包括任务描述、执行步骤、参考范例、输出要求甚至还能带上专用脚本。Agent在对话中通过语义匹配发现当前请求命中某个技能包时就会自动加载这套规则来执行。我打个比方。提示词像你每次都临时给实习生口述一遍工作流程说得详细与否全看心情Skills则像公司里的SOP手册新人来了直接翻手册就能上手干出来的活儿标准统一、质量可控。1.2 Skills与Prompt、Fine-tuning的边界在哪里很多人会问既然有Prompt为什么还要搞Skills既然能微调模型为什么还要用技能包这其实是三个不同层级的工具用对了场景各司其职。Prompt解决的是一次对话中的即时指令它的特点是最轻量改起来最方便但完全没有积累效应。你今天在对话框里写了一段很完美的指示明天想复用还得复制粘贴而且不同轮次之间的输出一致性几乎靠运气。Fine-tuning是改变模型本身的行为习惯成本最高需要数据准备、训练流程、版本管理更适合那些模型基础能力确实不够、且任务形态极其稳定的场景。对一个通用场景动不动就微调时间和算力成本都兜不住。Skills正好卡在中间它不改模型权重只是给Agent提供了一套更高优先级的上下文和操作流程。相比Prompt它有文件结构、有版本记录、能被自动检索相比微调它成本低、见效快、随时可调。一个粗暴的区分标准是如果这个任务你一个月要干二十次而且每次干的流程基本一样那就值得给它建一个技能包。维度PromptSkillsFine-tuning沉淀方式聊天记录/剪贴板结构化文件夹模型权重复用成本低但靠人肉复制低且自动匹配高需训练修改灵活性高中高低适合场景一次性的临时需求高频重复流程模型能力缺陷修补1.3 一个标准技能包到底长什么样实际打开一个Skills文件夹里面并不神秘。最常见的结构就是一个以技能名命名的目录包含一个核心的SKILL.md文件外加可选的参考资料与脚本文件。SKILL.md是整个技能包的主控文件通常用Markdown写成头部带一段结构化元信息声明技能名称和触发条件正文则写清楚这个技能要完成什么目标、具体分几步执行、输出时必须满足什么格式。这就像一本操作手册的封面加目录加正文。references目录里放的是参考资料可以是范例文档、业务规范、代码片段Agent在执行任务时会被指导去参考这些材料而不是把大量背景知识硬塞进提示词里避免上下文被无关信息撑爆。scripts目录则可以放Python脚本、Shell脚本这类可执行文件。比如一个技能包负责生成销售报表它就可以带着一个脚本Agent运行脚本去读取数据源再结合大模型的生成能力输出分析结论。Skills因此不只是更聪明的提示词它本身就是一个轻量级的自动化单元。我在实际整理时还习惯加一个CHANGELOG.md或者README.md记录这个技能的迭代历史和适用边界。别小看这个动作后面做维护时能省掉无数当初为什么要这么写的困扰。2. 设计一个Skills的完整思路从需求拆解到结构落地2.1 先判断哪些任务值得做成技能包动手写技能包之前最错误的一种思路是恨不得把所有事情都装进技能包里。技能包不是收藏夹更不是越全越好。我见过有人把一个数据分析技能包写得像百科全书从读取CSV到画图表到写报告全塞进一个文件夹结果Agent每次调用时既要点这个又要顾那个反而严重掉链子。判断一个任务值不值得做成技能包我用三个标准来筛是不是高频、边界是否清晰、判断标准是否明确。高频是硬前提。一个月都碰不到一次的任务做成技能包纯属自我感动。边界清晰指的是输入输出可以明确描述比如给我一周的工作日志产出结构化周报是清晰边界而帮我把工作做好这类模糊需求根本没法定流程。判断标准明确也很关键说白了就是你能说清楚什么样的输出算合格这样才能在SKILL.md里写出可验证的完成条件。我自己最常做技能包的任务是周报生成、SQL查询生成、代码审查、会议纪要整理、客户反馈分类。这几类任务有一个共同特点流程固定、要求稳定、每个人做出来的结果都该差不多。这种任务最适合固化成技能包因为它本质上是在把个人经验变成团队资产。2.2 技能包的四层内容结构目标、流程、知识、输出拿到一个需求后我会把技能包内容从四个层面来设计分别对应目标定义层、流程编排层、知识参考层、输出规范层。目标定义层写在最前面用来告诉Agent这个技能到底是干嘛的。注意这里不是写作文不要长篇大论讲背景和意义而是用一两句话点名任务类型和适用对象。我在元信息里的description字段通常这么写用于根据工作日志生成结构化周报仅处理文本类日志输入不适用于数据分析场景。这样写的好处是当Agent进行技能匹配时可以快速且精准地命中不会跟其他技能混淆。流程编排层是整个技能包的心脏。在这一层我要把完成任务的过程拆解成明确的步骤每一步给出操作指令。比如生成周报我会拆成先读取日志并识别项目维度再按项目分组汇总进展接着提炼本周成果与风险最后按模板输出。每个步骤之间要有逻辑顺序让Agent像一个听话的员工一样按流程办事而不是自由发挥。知识参考层用来放那些做这件事需要知道但又不该每次重复粘贴的内容。比如代码审查技能包里可以放一份团队编码规范文档客服回复技能包里可以放一份产品FAQ。这些内容放在references目录里Agent在对应步骤会自行查阅既保证上下文不被无关信息堆满又确保知识不丢。输出规范层则写清楚最终交付物的要求和格式。它是质量的守门员能直接决定做出来的东西能不能直接用。周报技能包我会写明输出必须包含项目名称、负责人、本周进展、下周计划、风险与求助五个部分且要用表格呈现项目数据。别小看这一层很多技能包效果不好就是因为只写做什么没写交什么。2.3 命名与检索让技能包能被Agent一眼相中设计技能包时一个特别容易被忽视但实际影响巨大的环节就是命名和元信息描述怎么写。技能包的触发逻辑是语义匹配也就是说Agent要能在收到用户请求时判断出该调用哪个技能包。如果你把技能文件命名为mytest或者aaa或者description写得含糊不清那这套技能包做得再好也派不上用场。我整理了一套自己的写法。命名用动词加对象直接点明能力比如generate-weekly-report、review-python-code、summarize-meeting-notes。description要包含触发场景、输入要求、输出结果并且把不适用的情况也说清楚。这里有一个实操心得我会在description里刻意埋几个同义词触发词。举个实际例子周报生成技能包的description里我会同时写出周报weekly report工作汇总项目进展整理这类常见说法。这样用户在日常对话中无论怎么说Agent都能准确匹配到这个技能包。技能包还有一个设计原则小而专。每个技能包只做一件事并且边界清晰。如果一个任务本身可以拆成多个独立环节那就分别做技能包再由主技能包在流程中依次调用子技能包而不是硬塞成一个巨型文件。这条原则我在实践中吃过大亏后才彻底贯彻后面排查问题部分会详细讲。3. 实操手记从零手写一个周报生成技能包3.1 准备阶段与目录结构搭建纸上谈兵没意思我直接用一个真实在用的例子来走一遍完整流程。我选的是周报生成技能包这个任务几乎每个上班族都逃不掉而且非常有代表性输入是散乱的工作记录输出是有结构、有重点的周报文档中间需要模型做信息归类、优先级判断、风险识别流程相当清晰。准备工作只需要两个东西一个支持技能包机制的Agent客户端现在主流Agent工具基本都原生支持Skills目录以及一个专门的文件夹来存放所有技能包。我建议个人项目的根目录就按标准结构来组织所有技能包统一放在同一个根目录下方便环境识别和版本管理。目录结构我会这样搭skills/ ├── generate-weekly-report/ │ ├── SKILL.md │ ├── references/ │ │ ├── weekly-report-example.md │ │ └── writing-guide.md │ └── scripts/ │ └── parse_work_log.py ├── review-python-code/ │ ├── SKILL.md │ └── references/ │ └── code-review-checklist.md └── summarize-meeting-notes/ ├── SKILL.md └── references/ └── meeting-notes-template.md这种按技能名分文件夹、每个文件夹内固定结构的方式是社区里最常见的做法好处是后续扩展新技能完全不影响已有技能Agent扫描时也能高效定位。3.2 编写SKILL.md主控文件让Agent按流程办事主控文件是整个技能包的灵魂。我先写元信息部分这里的产品是给Agent看的所以必须简洁、准确、可匹配。--- name: generate-weekly-report description: 根据用户提供的本周工作日志生成一份结构化、可直接汇报的周报。适用于工作日志为纯文本形式输出覆盖项目进展、成果、风险与下周计划。不适用于数据分析报告或财务报表生成。 ---元信息的两行是关键。Name字段用机器可读的短横线命名description字段要同时交代适用条件和不适用条件这能有效减少调用时的误命中。正文部分我按流程编排的思路拆成四个阶段识别与归类、提炼与总结、风险与计划、格式化输出。每一阶段给出明确指令同时标注要调用的参考资料和脚本。# 工作流程 ## 阶段1信息识别 1. 读取用户提供的本周工作日志逐条识别所属项目和任务类型。 2. 如果识别结果中存在项目归属不明确的信息按未归类事项处理不要擅自猜测。 3. 运行scripts/parse_work_log.py对日志进行清洗和统计。 ## 阶段2项目进展提炼 1. 按项目维度汇总本周完成的关键事项突出可量化成果如完成率、交付数量、Bug修复数。 2. 参考references/writing-guide.md中的措辞规范避免空话套话。 3. 每个项目下方输出2-5条要点按重要程度排序。 ## 阶段3风险与下周计划 1. 识别日志中可能阻碍项目推进的信息如依赖阻塞、资源不足、需求变更标记为风险项。 2. 结合当前进展和日志中提到的下一步动作生成下周计划。 3. 下周计划必须包含明确时间节点和责任人。 ## 阶段4按模板输出 1. 严格参考references/weekly-report-example.md中的结构和格式。 2. 输出内容必须包含本周总览、分项目进展、风险与求助、下周计划四大部分。 3. 项目数据用Markdown表格呈现每部分标题必须与示例模板保持一致。3.3 参考范例与脚本一个都不能少光靠指令还不够模型需要看到优秀长什么样才能稳定输出高质量内容。references目录里我放了两份文件。每周报告范例是典型的一周周报的完整样例。这里给Agent一个黄金标准比你在指令里写下十条规定都管用。我特意让范例里包含表格、量化数据、风险表述覆盖Agent可能遇到的各种输出形态。写作指南倒是比较短更像一份避坑清单。内容不多但每一条都是我在反复调教中总结出来的血泪教训比如不要使用做出了卓越贡献这类抽象表述每个项目要给出一个可验证的数字或事实以及不要把下周计划写成梦想清单必须有具体动作和时间点。至于scripts里的解析脚本我用Python写了一个简单但实用的版本。它的作用是把用户贴进来的杂乱工作记录按时间线重新排序统计不同类型任务的数量为模型后续提炼提供基础数据。#!/usr/bin/env python3 import sys import re import collections def parse_work_log(log_text): lines [line.strip() for line in log_text.splitlines() if line.strip()] task_counter collections.Counter() patterns { 开发: [开发, 实现, 编码, 代码], 会议: [会议, 讨论, 对齐, 评审], 排查: [排查, 修复, 解决, Bug], 文档: [文档, 方案, 设计稿], } dated_entries [] for line in lines: match re.match(r(\d{1,2}月\d{1,2}日?)[:]?(.*), line) if match: date, content match.group(1), match.group(2) dated_entries.append((date, content)) for category, keywords in patterns.items(): if any(kw in content for kw in keywords): task_counter[category] 1 return dated_entries, task_counter if __name__ __main__: input_text sys.stdin.read() entries, counter parse_work_log(input_text) print(时间线已整理共识别 {} 条记录.format(len(entries))) for category, count in counter.most_common(): print({}: {} 条.format(category, count))为什么不把所有处理都用大模型做而要加一个脚本一个很重要的原因是成本控制。简单的格式清洗和统计是确定性任务用脚本做又快又稳还能顺便减少大模型的误差大模型更适合的是需要理解和判断的环节比如提炼成果、识别风险。这个分工本身其实就是一条很关键的技能包设计经验。3.4 单元验证与效果调优从能用到好用到写完技能包不等于结束验证环节往往比写还耗时。我每次都要准备三组测试数据一组是标准日志包含完整且规范的记录一组是凌乱日志时间乱序、夹杂无关信息还有一组是极端输入比如只写了一句话或者全是开会记录。三种输入分别测试技能包在正常、一般、边缘情况下的表现。第一轮测试我啥也没调直接拿标准日志跑结果暴露出一个大问题输出的周报每个项目下都有五条要点包含了大量类似积极参与项目讨论这种正确但无用的话。原因在于指令里写按重要程度排序模型理解成了把能写的都写上。我在流程编排层加了一条硬性约定每个项目下最多输出三条要点且每条必须包含可验证信息。第二轮用凌乱日志测试发现时间乱序直接影响了提炼结果。日志里明明有周三完成的某项任务模型却把它归到了本周一的项目里。光靠提示词约束已经不够了这时我让parse脚本负责按时间重排强制模型在阶段1必须输出排序后的时间线从源头解决了这个问题。第三轮极端输入测试时又遇到新问题只写一句话的用户输入模型依然硬凑了一份标准周报。这件事本身有好有坏硬凑反而说明技能包够稳但内容价值很低。我给SKILL.md加了一个输入校验流程当识别到日志质量严重不足时先向用户提问澄清而不是直接生成内容。经过这三轮调整周报技能包才真正达到了我自己满意的状态。每次调整都只改动SKILL.md中对应的一个小节然后立刻重跑测试直到所有测试集通过为止。养成这样小步迭代、随时验证的习惯技能包的维护成本会低很多。4. 落地过程中的高频问题与排查思路实录4.1 技能包加载失败先查元信息格式技能包最容易翻车的场景第一个就是Agent根本不识别。我见过很多新手在本地把文件夹建好了SKILL.md写了一大堆结果对话时怎么触发都无效Agent还是像没看见一样。紧张忙乱之前先按优先级排查。第一顺位是SKILL.md的frontmatter格式YAML格式非常严格冒号后面必须有空格引号必须闭合否则解析器会直接罢工。我一开始习惯用中文逗号或者手滑多加个空格这类问题特别隐蔽。第二顺位是description字段的匹配度如果触发语句里的关键词和description内容差得远Agent匹配不上很正常。第三顺位才是文件路径问题确认技能包目录是否在应用扫描范围内以及目录名是否与name字段一致。我自己踩过最直接的一个坑是在SKILL.md里写满了感叹号和强调措辞以为越用力模型越容易注意到。实际上元信息解析和自然语言理解不一样格式规范比煽情有效得多。有次我把描述写成了该技能用于生成周报非常重要结果Agent直接忽略了这个包改成正常描述后秒恢复。4.2 效果不符合预期技能包不是万能灵药另一种高频问题是技能包被成功调用了但输出依然不理想。这时候先别急着怀疑模型笨重点检查你是否把预期设置错了。技能包本质上是在约束大模型的行为路径而不是给大模型凭空增加能力。如果任务本身超出了模型的能力边界比如需要模型做精确的多位数乘除法、需要它记住你上个月的对话内容那技能包写得再细致也无济于事。这种情况要做的是换模型或者用scripts里的脚本去弥补那些确定性能力而不是在SKILL.md里继续堆要求。还有一个更隐蔽的问题叫提示词冲突。技能包里的输出模板和其他系统指令打架比如系统里本身要求所有回复都用中文但技能包范例是英文的。这时候模型会陷入不知道该听谁的状态表现就是输出风格忽好忽坏有时严格按照技能包来有时又跑偏回通用回复。排查方法很笨但很有效拿掉技能包只保留系统提示词看模型表现是否恢复正常。如果恢复正常说明问题出在技能包与系统指令存在冲突如果还是不行那就要往其他方向排查。4.3 技能包之间发生冲突边界不清惹的祸技能数量一多新的问题就来了。我同时装了生成周报、整理会议纪要、撰写项目总结三个技能包最初它们的description里都写了输出结构化文档结果用户给了一段会议记录时Agent居然分不清该调哪个包有时甚至同时加载两个包输出内容互相重叠。那一次排查让我把边界设计的重要性彻底记住了。现在的解决方案是在每个技能包的description里明确写清适用对象和不适用对象。比如周报技能包就写明仅处理工作日志不处理会议记录会议纪要技能包就写明仅处理会议原始记录不处理个人日志。看起来只是几行字但语义空间被切割开了匹配准确率提升非常明显。另外技能包之间确实存在协作需求时我会明确写成主从调用关系让流程编排层去调度子技能包而不是让Agent自己去猜测。比如周报生成在阶段1可能调用会议纪要整理来从会议记录中提取项目进展这种调用关系在SKILL.md里写清楚Agent就会按编排执行不会混乱。4.4 安全边界技能包也要有白名单思维技能包的使用还牵涉到一个容易被忽略的安全问题。脚本可以执行确定性操作如果这些操作涉及读取文件、发请求、改配置就一定要有边界意识。我给团队定的铁律是技能包内的脚本默认不允许执行任何有副作用的操作。想读文件必须限定在指定目录内读取不放开全盘任意访问想发起网络请求先过配置白名单不允许技能包自带任意发请求的自由。这条经验是我身边一个同事被坑之后才总结出来的当时他的一个技能包里不小心写了一个对环境变量进行修改的脚本测试时直接把开发环境带崩了。技能的权限边界和功能边界一样重要。SKILL.md里除了写做什么还得写明不做什么、哪些操作必须经过用户确认。这不是证明你考虑周全而是保证你的技能库真的可以长期稳定运转。5. 我把Skills用起来的几条心得与后续扩展思路5.1 三个特别容易忽略的细节第一个细节是版本管理。技能包迭代了两轮之后你很可能说不清当前版本和上一版差在哪。我的做法是在每个技能包的目录里放一个CHANGELOG.md每次修改必须记录改动日期、改了哪一层、改动原因。这个习惯一开始有点繁琐但等技能包数量超过五个你会感谢当初的坚持。第二个细节是维护节奏。技能包不是写完就永远不用管的死文档。业务在变团队规范在变写好的技能包会慢慢过期。我现在给自己定的维护周期是一个月过一次所有技能包每个技能包在最近三十天内的调用次数、输出质量、用户反馈都会被仔细翻出来看一遍。调用的少要想想是不是功能太鸡肋反馈不好的要看看具体卡在流程编排还是输出规范。第三个细节是要建立一个反馈闭环。技能包真正使用起来之后使用者的反馈远比你的自测有价值。我会刻意让团队成员在用完技能包后顺手标注一下输出内容是否有误、哪里需要改。这些反馈经过一段时间的积攒最后都会沉淀回技能包的下一次迭代里。5.2 从个人效率工具到团队基础设施技能包这个东西单人使用和团队使用完全不是一个量级。单人的时候你自己心里清楚每个技能包能做什么、不用怎么费心管理。到了团队技能包就有了基础设施的属性需要统一命名规范、统一目录结构、统一评审机制。我见过最有意思的团队做法是把技能包当作内部知识库的活体版本。编码规范、文档模板、运维手册这些原本静态存放的资料全部拆解后封装进对应的技能包让Agent在干活时顺手就把规范用进去。这比让人去翻知识库高效得多因为规范不是在被查阅时才存在而是直接融入了工作流本身。演进路径上也有些值得参考的实践。一个人做技能包先从每周都会重复的任务开刀比如周报、会议纪要、客户回复做到三五个后尝试把有依赖关系的技能包编排成一条流程链接着再考虑把它推给团队配套建立评审与反馈机制。每走一步都是在把分散的个人经验压缩成可复用的组织能力。5.3 我更看好的三个扩展方向就我目前实践经验来看技能包最值得关注的后续方向有三个。第一个方向是跨平台迁移。现在各家的Agent平台都开始支持统一格式的技能包同样的技能文件夹在本地客户端和在线工作流平台之间可以来回携带。这意味着技能包的标准化程度还会继续提高一套写好到处可用价值远大于在单一平台内嵌死的规则。第二个方向是技能包与自动化工作流的深度结合。技能包不光可以在对话里被触发还可以嵌入到定时任务、事件驱动的流程里比如每天定时读取项目管理系统里的更新自动生成项目日报发送到群里。这个时候技能包就从你问它答的工具变成了真正干活的生产流程。第三个方向是让技能包学会自我进化。我的设想是在技能包里加入结果评估机制每次执行完自动收集用户反馈根据历史效果建议下一版在哪些环节做调整。这个闭环一旦跑通技能包就不只是固化经验还能持续优化经验本质上变成了一个能自我迭代的流程机器人。最后再分享一点我自己的感受。用了大半年的技能包之后我最大的收获反而不在省了多少时间而在于它逼着我把脑子里的模糊经验一点点讲清楚、写出来、变成别人也能理解和执行的东西。这个过程中暴露了不少我自己都浑然不觉的思维盲区说句实话这份收获比省下来的那点时间值钱多了。希望这篇文章也能帮你把经验真正沉淀下来。