从提示词到技能包：大模型 Skills 实战拆解与避坑指南

最近这半年我和身边的开发者朋友聊得最多的一个词就是 skills。不是简历上的那些技能列表而是 AI 圈正在悄然流行起来的一种新玩法——把复杂任务里那些只可意会、不可言传的经验和规则打包成结构化的技能包喂给大模型去执行。我第一次意识到这东西的分量是有一次让 AI 助手帮我整理一份技术方案评审意见结果它像第一次进考场的学生答得全但完全不着重点。而当我给它塞了一个写好的 review skills 之后输出质量直接上升了一个档次——该追问的地方追问该放行的地方放行比很多刚入职半年的初级工程师靠谱。也就是从那天起我决定认真研究 skills 到底是什么、该怎么写、有哪些坑。这篇文章不是我翻译文档的读书笔记而是我折腾了一个多月、在真实项目里反复迭代后的实战总结。如果你正在用 AI 辅助开发、写文档、做数据分析或者单纯觉得大模型用起来总差着一口气那这篇文章应该能帮你把这口气补上。我会从原理讲到实操再拿出一个可以照抄的完整案例最后把我踩过的坑一个个翻出来给你看。1. 为什么 skills 突然成了香饽饽1.1 通用模型的能力边界在哪先想一个很朴素的问题一个大模型知识量相当于读了整个图书馆但让它帮你写一份符合你们团队风格的代码审查意见它为什么经常写得四平八稳、毫无灵魂原因是它缺少岗位经验。模型知道代码审查这个概念的定义但它不知道你们团队要求重点检查哪几类问题、你们默认什么样的代码算风格合格、你们的历史项目里踩过哪些深坑。这些信息不在通用知识里而是在你的项目沉淀里。你就算在对话里反复叮嘱它也会漏你写一段很长的提示词它执行到一半就开始忘。我打个比方通用大模型像一个成绩很不错的应届生基础知识扎实但没有岗位培训手册干起活来全凭常识瞎蒙。而 skills 就是那份岗位培训手册把一整套做事规则、判断标准、注意事项整理成它看得懂的形式上岗之前先照着培训一个月。1.2 传统提示词工程的三个硬伤有人会说那我写提示词不就行了我把规则写进 system prompt 里把案例塞进上下文里不也能实现类似效果吗能但很难规模化。第一个硬伤是上下文窗口的内存泄漏。你写一个 2000 字的系统提示词每轮对话都要背着这 2000 字运行token 成本高、响应速度慢。等你塞三个任务、五个历史案例进去上下文直接被占掉大半模型真正用来思考的空间就小了。更麻烦的是多个任务的提示词互相污染——你让模型一会儿扮演代码审查员一会儿扮演文案写手角色切换时经常串味。第二个硬伤是不可复用。你在这个项目里调好的提示词换到另一个项目就用不了因为里面有大量项目特有的描述。哪怕同一个团队换个成员接手又得重新调一遍。第三个硬伤是没法迭代维护。提示词都是一坨纯文本改一处就得整体调整没有结构化目录也没有版本管理。时间一长没人知道这段提示词里哪些规则还有效、哪些已经过时了。skills 解决的就是这几个问题按任务拆分职责、按目录组织知识、按版本维护规则。它不是提示词的替代品而是提示词的工程化升级。1.3 把个人经验变成团队资产我真正决定投入精力研究 skills是因为一个很现实的团队场景。团队里有一位资深工程师他做代码审查又快又准但他凭的是十几年的经验积累。我们尝试把他的审查要点写成文档文档有了但没人在日常流程里真正去读——太长了而且还得靠人判断什么时候该用哪一条。后来我们用 skills 把他的审查思路做成了结构化的技能包放进团队的 AI 工具里。效果非常明显新人提交代码时AI 助手能按资深工程师的标准给出初审意见新人再去改资深工程师只需要看后半程。一个人的经验通过 skills 的形态变成了团队基础设施。这就是我觉得 skills 最大的价值——它让经验不再是人身上的软技能而成了可复制、可维护、可迭代的资产。2. skills 到底是什么和 prompt、插件别再傻傻分不清2.1 一个 skills 的标准结构拆解按我目前实践下来的理解一个完整可用的 skills 应该包含四个部分。第一部分是描述文件用来告诉模型这个技能是干什么的、在什么情况下调用。这部分决定了模型会不会在合适的时机想起它。第二部分是使用说明通常是一个核心文档相当于操作手册正文详细写清楚执行这个任务的步骤、原则和关键注意点。第三部分是知识库里面可以放术语表、规则清单、历史案例等参考材料对应模型执行时的参考资料库。第四部分是可选的动作脚本或模板文件比如读取某个目录、生成某种格式的输出。我自己的习惯是用一个统一命名的文件夹来管理里面至少放两个核心文件一个是描述信息一个是主执行文档。知识材料按需增加用子目录组织。这样结构清晰模型读取时也不会迷路。打个比方。你给一个新来的实习生交代工作只口头说一句帮我整理一下客户资料是不够的。而 skills 相当于同时给了实习生一份职责说明描述文件、一本操作手册执行文档、一叠参考模板知识库告诉他什么时候该做这件事、具体怎么做、输出成什么样算合格。2.2 skills 和 prompt 模板的本质差异很多人刚接触 skills觉得这不就是一套写好格式的 prompt 吗还真不是。prompt 模板本质上是一次性指令。你把它粘进对话框它起到的是引导作用任务结束它就完成了使命。而 skills 是持久化能力。你可以随时把它装载到模型身上模型在遇到对应任务时会自动尝试调用它。prompt 是你在前台跟模型说的话skills 是后台给模型配好的岗位能力。还有一点很关键prompt 的可扩展性和可维护性都很差。而 skills 的核心文档可以拆分成多个文件用逻辑目录组织遇到更新只需要动对应文件夹里的一小块内容不用翻一长段 prompt 去找那半句话。我见过有人把 3000 字的 prompt 塞进 system prompt效果勉强能用但每次改动都堪比做一次手术。如果你发现自己正在维护一份越来越长的 prompt而且开始记不清里面写了什么那确实是时候把它结构化成一个 skills 了。2.3 skills 和插件、工具调用的分工再聊聊 skills 和插件/工具的关系。很多人容易把这两者混为一谈其实它们的定位完全不同。插件或者工具调用的核心是外挂能力——比如让模型能搜索网页、能执行代码、能访问某个 API。这些能力是模型原本不具备的手和脚。而 skills 的核心是内化经验——是让模型知道一件事按什么流程做、用什么标准判断。你可以把工具理解成给模型一把螺丝刀而 skills 是告诉模型在什么场景下用螺丝刀、拧到什么程度算到位、拧坏了怎么处理。两者并不互斥反而是天然互补的。一个优秀的 skills 往往会在执行文档里声明先调用某某工具获取数据再进行规则校验——它既包含经验判断也包含动作调用。最理想的状态是工具负责执行动作skills 负责指导动作。我在实际项目中通常是先设计 skills 的执行流程流程里涉及具体动作的地方才考虑接工具。顺序不能反先定打法再选家伙。2.4 什么场景适合用 skills、什么场景别用skills 不是银弹它有非常明确的能力边界。我总结了一下适合用 skills 的任务有三个特征高频、有稳定流程、有明确交付物。典型例子有代码审查、周报生成、项目复盘、数据分析报告、客户邮件回复等。这些任务重复发生每次执行步骤相似而且输出结果可以对照标准来验收。反过来有三类场景不适合用 skills。第一类是一次性创意任务比如头脑风暴一个营销主题这种任务每次的语境都不同标准化反而会扼杀创造力。第二类是高度依赖实时信息的任务比如查最新行情、看今日新闻这种应该直接接实时数据源而不是做死板的 skills。第三类是流程完全不确定的探索性任务比如调研一个新领域的技术选型连步骤都还没定型固化它只会让模型机械地走老路。重点说一句skills 的价值在于稳定地复现一个已经想清楚的流程而不是帮你思考一个还没想清楚的流程。想清楚再做不要为了 skills 而 skills。3. 手把手教你从零设计一个自己的 skills3.1 第一步判断哪些任务值得做成 skills在动手之前先做一个任务盘点。把你自己日常工作中反复做的事情列出来找高频且耗时的那几项。这是最优先的候选池。我曾经列过一份自己的清单里面有代码审查、写周报、整理发布说明、回复客诉邮件、制定项目排期等。然后我用三个筛子过滤第一每月是否至少发生三次以上第二执行步骤是否相对固定成熟不是每次都临场发挥第三产出物是不是有明确的格式或质量标准。三个条件全满足的才值得花时间去做了固化。这里有一个非常容易犯的误区一上来就挑最复杂的任务做 skills。我以前也这么干过选了全栈项目代码审查这种超大技能结果文档拉到五千字模型读不完执行质量非常差。正确的做法是先挑一个中型的、边界清晰的任务比如前端合并请求的变更审查先跑通一遍全流程再慢慢扩大范围。3.2 第二步把专家经验拆解成可执行的规则选定任务之后第二步是最考验功力的提炼规则。你要把脑子里模糊的经验变成一条一条可以执行验证的判断标准。我拿生成项目周报来举例。很多人觉得这还不简单让模型把本周工作列一下不就行了但资深项目经理的周报是有讲究的要突出进展而不是罗列动作、风险要归类、数据要有对照、下一步要和风险形成闭环。这些讲究就是经验得一条条拆出来。我常用的方法叫反例驱动提炼。具体操作是收集五份你觉得质量不太行的旧周报然后逐一分析为什么不行。比如有一份周报把开会写成了成果另一份没有区分进行中和已延迟的任务。每分析出来一个缺陷就把它转化成一个正面规则写进 skills 的执行文档里。这种方式比凭空列规则实用得多因为每条规则都有真实的失败案例做支撑。拆解规则时要注意颗粒度。太粗的规则比如分析风险模型不知道具体怎么做太细的规则比如风险描述必须包含责任人、影响范围、处理期限、下周计划又容易让模型死板套格式。我的经验是普适原则和具体动作各保持一半原则给模型思考空间动作给模型落地抓手。3.3 第三步写描述信息和主执行文档结构化的核心是文件怎么组织。我先说推荐的最小目录结构你直接照抄就行。skills/ └── project-weekly-report/ ├── SKILL.md └── references/ ├── examples/ ├── rulebook.md └── template.md最关键的文件是 SKILL.md。它负责向模型自我介绍内容质量直接决定模型什么时候会调用这个技能。我实践下来一份好用的 SKILL.md 包含几块内容开头用两三句话说明这个技能是干什么的然后明确何时使用和何时不使用——这两个 positive 和 negative 触发条件都很重要可以显著降低模型误调用概率。接下来写执行要求比如必须先读某目录、必须按照 rulebook.md 校验、输出必须遵循 template.md 格式这几条相当于告诉模型执行时要注意什么。最后是移交标准说明产出的东西交给谁、下一步谁负责。这里有个很容易忽略的细节SKILL.md 不是越长越好。模型加载技能描述时靠的是对整段文字的语义匹配如果你写得太长太乱反而会干扰匹配效果。我的经验是控制在 15 到 30 行以内重点突出细节内容全部放到 references 子目录里。描述文件只负责说清楚这个技能是什么执行细节让模型真的被调用之后再去读参考文档。3.4 第四步用真实数据和失败案例做测试写完初版之后最忌讳的就是立刻投入使用、拿真实任务当小白鼠。我的习惯是把历史数据整理成测试集进行批量验证。以周报技能为例我拿出过去三个月的真实数据每条数据对应一份当时人工写的周报作为标准答案然后让模型用这个技能去生成对应的周报再逐条比对。比对的重点不在于文字一模一样而在于结构是否合理、风险是否识别齐全、表述是否符合团队习惯。测试之后你会发现很多意外问题。比如我第一版技能生成的周报把本周做了五件事这种流水账全部当成进展而资深专家会把它提炼成一个重要进展 两个平稳推进又比如风险识别老是漏掉外部依赖滞后这类非显性问题。每个问题都是一个信号指引你去修改 rulebook.md 里的规则或者参考案例。这个过程需要迭代至少三四轮。别嫌麻烦你在测试阶段每抓到的一个问题都是实际使用时能避免的一次返工这笔时间花得值。3.5 第五步定版本、留变更记录、决定共享方式最后一步容易被新手忽略但却是 scale 到团队协作的关键版本管理。skills 不是一个写完就固定的文件它和代码一样需要持续迭代。我给自己建的每个技能都会维护一个 CHANGELOG 记录简单记录每版改了什么、为什么改。比如v1.2增加数据对齐规则因为旧版漏报跨部门依赖风险。这会在后续很多版本之后帮你做判断——也顺便决定哪些规则是曾经试过但后来被淘汰的。另外还要考虑共享范围。如果是个人使用文件夹放在本地就行。但如果是团队共用就得考虑集中式管理避免每个成员本地维护一份、越改越不一样。我们自己的做法是把 skills 目录放进团队代码仓库走合并请求评审机制谁来改都要经过评审这个机制跟代码协作是同一套逻辑。4. 实战复盘写一个代码变更审查技能全流程4.1 设计目标和触发场景这一节我拿自己最近在用的代码变更审查技能做完完整案例拆解。这个技能的核心目标是对开发人员提交的代码变更简称 MR/PR进行第一轮自动审查输出结构化意见让资深工程师只需要关注 AI 筛出来的重点问题。先明确触发场景。这个技能不会在所有对话里都生效只会在满足以下条件时调用用户要求审查代码变更、用户给出变更描述或涉及的文件列表、用户明确提到帮我看下这次改动有没有问题。我在 SKILL.md 里特意写了不要把普通问答当成审查请求这能防止模型在莫名其妙的时候自作主张调用它。设计时我还确定了三类输出要求阻塞性问题必须修改才能合并、建议性问题最好修改但可商量、疑问点需要作者解释。这个分级参考了行业里成熟的分层评审思路能让输出信息更结构化。4.2 目录结构和关键文档内容这个技能的目录结构是这样的skills/ └── code-review/ ├── SKILL.md ├── references/ │ ├── rulebook.md │ ├── security-checklist.md │ ├── examples/ │ │ ├── good-review-example.md │ │ └── bad-review-example.md │ └── templates/ │ └── review-report-template.md └── scripts/ └── extract_diff.py其中 SKILL.md 是入口文档我写得比较克制核心内容主要是触发条件和执行流程的简述# Code Review Skill 对代码变更提供结构化、分级的审查意见帮助把关代码质量。 ## 何时使用 - 用户要求审查代码变更MR/PR - 用户上传或指出待审查的代码文件 - 用户希望评估本次改动的风险等级 ## 何时不使用 - 普通的技术问答 - 讨论某个通用 API 用法 - 用户未指定具体代码或变更范围 ## 执行步骤 1. 读取变更涉及的文件和 diff 内容 2. 从 rulebook.md 加载审查规则 3. 对照 security-checklist.md 检查安全问题 4. 按 template 输出分级审查意见 ## 输出要求 必须包含三部分问题清单、修改建议、风险等级判断references 目录下的 rulebook.md 是核心知识库。里面按正确性可维护性性能一致性几个维度写规则每条规则都配一个简短的例子。security-checklist.md 则是受团队历史教训驱动整理的检查项比如禁止硬编码密钥、日志中不允许打印敏感字段、对外接口必须做参数校验等。4.3 从初版到可用的迭代过程这个技能第一版只用了两周多时间上线后我发现它效果相当一般主要问题是三条审查意见偏通用、缺乏项目特有约定、安全项漏检率高。第一个问题表现在意见过于教科书。比如总是提示函数过长建议拆分但项目里很多核心逻辑函数本来就很长强行拆分反而降低可读性。我把这类规则从硬性规则降级为可选建议并在规则库中注明适用场景模型的输出立刻变得靠谱很多。第二个问题是因为团队有自己的约定比如后端请求校验统一用某框架注解、前端状态管理遵循特定目录结构。这些约定在通用规则里没有需要我在 rulebook.md 里专门建一个项目约定章节把团队规范逐条写进去。第三个安全问题最难缠因为安全规则不能靠通用常识覆盖它高度依赖漏洞案例的积累。我后来的解决办法是维护一个安全案例库每出现一次真实安全事故就把出错模式记进 security-checklist 里标注为必须阻塞模型下次就会重点排查同类问题。4.4 效果对比和可迁移经验这个技能从初版到 v2.3 版本我只保留了能提升实际质量的规则删掉了大量理论上应该检查但实际没人看的空洞条目。目前体量是你管它叫胖技能也不为过。因为核心迭代逻辑是可复制的找真实问题、定位规则缺失、改规则、回归测试、再上真实任务。这条循环跟写代码是一样的唯一区别是改动对象从代码变成了文档和知识。顺便说一句这个案例完全可迁移到别的场景。比如把代码审查换成方案评审、数据分析、客服回复逻辑是一样的。你先定边界什么时候触发再搭知识库身份规则、历史案例、检查清单最后用真实输出持续反推修订。这套方法论比任何具体的技能文件都值钱。5. 避坑手册我踩过的五个大坑5.1 贪多求全一次加载几十个技能第一次用上 skills 的时候我下载了一堆别人分享的技能然后全部塞进工具里心里美滋滋想着这下 AI 什么都会了。结果模型开始变得很奇怪经常答非所问。后来我复盘下来核心原因是技能加载过多导致选择性混乱。模型一次能记住的技能描述是有限度的一是同时加载太多会稀释每个技能的识别准确率二是存在触发条件重叠冲突的问题。形象点说就好比一个实习生面前堆了几十本不同岗位的手册他反而不知道该听哪本了。这是使用 skills 最重要的一条纪律重质不重量。我现在的原则是每天的工作场景里实际高频使用的技能维持在五个以内其余全部存档谁要用谁再临时加载。5.2 触发描述太模糊该用的时候它不出现另一个我早期常见的困扰是我已经写了触发条件但跟模型对话时它就是不调用这个技能。检查下来发现是 SKILL.md 里的何时使用描述和用户真实表达习惯对不上。举个例子。我写技能时用词是代码变更审查用户在实际对话里说的是帮我看看这次改得行不行。模型在后台做语义匹配时这两句话的相关度和用户表达是存在距离的匹配不充分就直接不调用。解法是给描述加同义句启发式信息。我会在何时使用部分写出用户可能说的各种说法比如看下这个 PR、检查一下代码改动、这些变更有没有问题。相当于给模型多几个样例句做参考触发准确率明显提高。这件事做一次后续使用能省很多临场纠错的功夫。5.3 知识库堆成百科全书模型读不下去第一次写知识库我总是恨不得把相关的所有资料全部放进去。结果核心文档 8000 字模型每次执行都要读一遍既影响速度又影响质量——太多无关细节干扰重点判断。后来我调整思路参考资料只放决策边界和检查清单不放概念性解释。比如写代码审查技能我只需要放什么样的问题算阻塞、什么样的算建议、具体检查哪几个点而不需要放什么是代码审查。模型的本体知识已经够用skills 补充的是判断标准和本地经验而不是通用的领域知识。注意知识库负责提供标准和判断依据不是给模型补课的概念讲义。如果你发现自己写了大量XX是什么的内容说明你的技能定位出了问题。5.4 规则改出一处别处就出错这个坑特别隐蔽也是几乎所有系统迭代都会面临的经典问题改了规则 A原来正常的规则 B 突然开始犯错了。我举个例子给周报技能增加一条风险描述必须包含数据佐证结果后发现模型为了满足这条要求在没有任何数据风险的时候强行编了一个风险数据出来。规则太死反而诱发了幻觉。解决办法是每次只改一条规则并且回归全部历史测试集。如果一个技能的最大特质是互相耦合比较强的那就更应该坚持单变量控制。另外规则里要多写例外情况比如上述那条数据佐证规则我后来变成如果风险是由外部因素导致的允许不提供量化数据但需要说明信息来源。5.5 过度设计完美主义让技能越来越笨最后一个坑可能要算心态层面最难走出来的过度设计。我一度想把技能做得完美把所有团队规则、所有历史案例全塞进去结果技能的执行变得极其死板生成的内容全是一个模子没有自己发挥的余地。后来我接受了一句评价skills 的目标不是取代人而是把经验流程化让人从重复劳动里解脱。技能提供一个合格线超过合格线的创造性发挥留给使用者。所以现在我每个技能都会在 SKILL.md 末尾写一句话遇到规则覆盖不到的情况基于原则判断不要强行套规则。这句话很轻但实际效果很好模型在模糊场景下的应变能力大大提升。6. 一些提升 skills 质量的野路子技巧6.1 用反例驱动持续更新知识库前面提过我用反例驱动做初始规则其实这个思路更长期的价值在于持续迭代。每次你发现技能输出的结果不对劲不要只修这一次的问题而是问自己这个错误暴露了哪条规则缺失或者哪条规则有歧义我会给每个技能维护了一个失败案例文档里面记录每次失败的输入、错误输出和原因分析。每个月抽半小时翻一遍这个文档归纳共性然后更新到规则库。这个过程跟用缺陷报告驱动代码修复一模一样是最可持续的质量提升手段。6.2 让技能之间可以串联而不是堆砌技能和技能不是孤立的。我现在的做法是把复杂任务拆切成多个小技能再通过技能编排把它们串联起来。比如一次完整的发布流程可能先调用变更审查技能再调用生成发布说明技能最后调用核对发布检查单技能。关键点是技能之间要靠清晰的交付标准衔接前一个技能的输出要能被后一个技能识别为输入。你自己设计两个技能时就要考虑一个人——技能的接口定义好串联才顺得起来否则每次串联都需要额外解释效率大打折扣。6.3 控制更新节奏给技能留出稳定期最后一条是关于更新节奏的经验不要每次想到一个好点子就立刻改技能。我给每个技能定了更新窗口一般是每周集中处理一次把攒下来的问题一次改掉。这样既保证了技能相对稳定又能在每次更新时做足够好的回归测试。如果每天都改你根本分不清哪次改动带来了哪个效果最终只会越改越乱。在我实际使用的这段日子里最深的体会是skills 是一个典型的慢就是快的事情。初版都难看但只要迭代方向对三个月后回头看你的效率提升会非常明显。它不用你有多高深的技术功底考验的是你愿不愿意把事情拆细、把经验讲清楚。如果你手头正好有一个重复做了很多次的任务不妨就从这个任务开始照文章里的流程试一遍感受一下什么叫把能力沉淀下来。