二十多套“一次性”提示词用下来我发现自己一直在重复造轮子。今天要说的不是某个具体框架而是围绕 skills 这个词展开的一套方法论——把高频任务沉淀成可复用、可版本化、可共享的技能包。先说清楚它是什么skills 不是一条提示词而是一个有目录结构、有元信息、有清晰指令的文件夹是介于“普通 Prompt”和“完整项目”之间的能力单元。它能解决的问题很实际你不需要每次对接模型都重新解释你的项目背景、编码规范或审查标准让模型以更稳定的方式完成一类任务。这篇文章面向的读者是每天在使用大模型写代码、做分析、写文档的开发者以及想把自己工作流产品化的技术负责人。我最初接触 skills 是因为一个很蠢的场景我给同一个仓库做了第三方代码审查每次都把同样的规范贴进对话里模型理解的深度还忽高忽低。后来我把这些规范整理成了一套 code-reviewer 技能包输出瞬间稳定了而且新加入的成员也能直接用。我想聊的就是这套思路的完整落地路径包括目录设计、SKILL.md 的写法、依赖处理、版本管理和坑。1. 为什么你需要一套自己的Skills1.1 从重复劳动到资产沉淀我们先做一个计算。假设你每天和模型交互十次其中有四次要交代背景信息——项目技术栈、目录结构、编码偏好、不要做什么、尽量做什么。每次交代信息如果按两百字算一天就是八百字一个月两万四千字。这些字并没有消失它们消耗的是你的时间、心智和上下文窗口。而这些信息本质上是你这个团队、你这个项目最重要的隐性资产它们散落在聊天记录里而不是被结构化管理。把同样的信息抽出来写成 SKILL.md这个动作的价值不只是一次性省了几百字。它是在把你头脑中的上下文外部化。之后你甚至不需要完整描述任务只要说“按 code-reviewer 的方式审一下这次改动”模型就会去加载对应的技能包。更重要的是技能包可以被其他成员使用。团队里每个人都会从同一套标准出发不会出现三个人有三种审查口径的情况。我认识的一位后端开发把自己做接口设计时的约束整理成了一个 api-designer 技能包里面写清楚了鉴权方式、返回码规范、分页形式和异常处理边界。原来带新人时他要口头讲半个小时现在新人自己让模型按这个技能包出方案他只需要 review 结果。这就是从重复劳动到资产沉淀的转变。1.2 Skills与普通提示词的本质区别很多人会问skills 和我在提示词里写“你是资深专家请遵循……”有什么区别区别非常大。普通提示词是线性的、易失的。它跟着对话走模型在长上下文里很容易“忘记”你最开始设定过什么。而且提示词缺乏结构没有明确的输入输出约定没有文件级别的组织。你在一个对话里写“你是一个严谨的代码审查者”下一个新对话又要重复一遍。Skills 做的事情是给模型一个预先编排好的“工作手册”而且这份手册是结构化存储的。它有明确的名称、描述、使用场景甚至可以带上辅助文件、脚本和模板。模型在启动这类任务时会像加载插件一样读取整份技能定义而不是依赖你刚刚说的那几句话。另一个区别在于可测试性。提示词很难做质量评估但技能包可以。你可以定义“输入端是什么、输出端是什么、质量门槛是什么”然后跑一组测试用例来检验这个技能是否达标。这已经接近软件工程的做法了。1.3 什么场景最适合Skills化不是所有任务都适合做成 skills。我的经验是三个特征高频、稳定、有边界。高频指的是你一周至少会用到两三次的任务。太冷门的东西不值得花时间封装。稳定指的是任务的输入输出比较明确比如“为这个函数写单元测试”“审查这段代码的安全性”“把这次更新的发布说明总结成对外公告”这类任务有固定的套路。有边界指的是你能把任务的边界写清楚不至于一个技能包变成一个大杂烩。反过来那些开放式的头脑风暴、探索性研究、纯聊天场景就不太适合做技能包。因为这些任务本质上需要的是发散不是收敛它们需要模型的创造力而不是你的约束。硬把它们套进技能包反而会把模型的发挥空间压死。我也见过有人把整个项目的完整开发流程塞进一个技能包里结果模型执行到一半就乱了因为流程里的分支太多单靠一份文档无法覆盖所有情况。更好的做法是把流程拆成多个技能比如一个负责需求拆解一个负责接口设计一个负责写实现一个负责审查。每个技能只做好一件事技能之间通过约定好的“交接文档”衔接。2. Skills的骨架设计2.1 SKILL.md让人和模型都能读懂的说明书SKILL.md 是整个技能包的核心入口。它至少要包含四类信息元信息、触发条件、执行步骤、质量约束。元信息是最容易被忽略但很重要的部分包括技能名称、简短描述、适用场景、作者和版本号。描述写好了模型才能在你没有明确点名技能名时主动想到该用哪一个。我在实际测试中发现描述里最好明确写出“当用户说要做什么时使用”并且给两三个典型的用户表达方式作为示例。比如 code-reviewer 技能的描述可以写成对代码变更进行结构化审查并输出风险清单。当用户说“帮我 review”“检查这次改动”“审一下这段代码”时使用。模型读到这个描述就能做很好的触发匹配。执行步骤要用命令式语气来写而且要写给模型看。很多 SKILL.md 写得像散文通篇“我们应该……”“我们需要……”模型读起来约束力很弱。正确写法是像算法步骤一样一条一条列清楚比如“读取变更涉及的 files 清单”“逐一检查每个文件是否符合 reference/ 下的规范”“对每个发现标注严重级别”“输出审查报告并附带修改建议”。质量约束这一块也很关键。要让模型明确知道什么不能做、输出格式是什么样的以及评分标准是什么。比如代码审查技能可以写明所有发现的问题必须附带行号不确定的问题标记为“需要人工确认”不得使用“代码质量较差”这类模糊表述每个严重问题必须给出具体的修复示例。2.2 目录与文件组织一个标准技能包的结构长这样skills/ ├── code-reviewer/ # 技能根目录 │ ├── SKILL.md # 技能说明书 │ ├── reference/ # 参考材料 │ │ ├── checklist.md # 审查清单 │ │ └── style.md # 团队编码风格 │ └── scripts/ # 辅助脚本 │ └── parse_diff.py # 解析变更文件这里有个细节值得注意技能包内引用的文件路径要使用相对路径并且约定工作目录。模型在读 SKILL.md 时会把技能包内的 reference 文件当成带外知识加载。如果你的脚本需要依赖外部环境SKILL.md 里要写清楚依赖项和运行方式。辅助文件不是越多越好。我见过有人把一堆 PDF、图表、完整代码库都塞进技能包结果模型加载时上下文爆炸输出质量反而下降。技能包里的辅助文件应该是“摘要级的参考材料”而不是“完整的知识库”。如果某个规范文档很长应该先提炼一份精简版放进技能包完整版链接放在文末供人工查阅。2.3 一条可运行的技能模板直接给一个能跑的模板。我以“单元测试生成器”为例它的 SKILL.md 完整内容如下--- name: unit-test-writer description: 为指定函数或模块生成单元测试。 当用户说“给这个函数写测试”“补一下单测”“测试覆盖率不足”时使用。 version: 1.0.0 author: team-core --- # 单元测试生成技能 ## 输入 - 待测函数的源码文件路径 - 可选测试框架偏好pytest / vitest / go test - 可选需要覆盖的边界条件列表 ## 执行步骤 1. 读取函数源码识别主流程、异常分支和依赖项。 2. 根据 reference/test-template.md 中的模板结构生成测试文件。 3. 对每个分支至少编写一个测试用例若无法覆盖在报告中说明原因。 4. 生成测试文件后检查是否包含正常路径、边界值、异常输入三类用例。 5. 输出测试文件内容并用“测试要点”小结说明每个用例的意图。 ## 质量约束 - 测试文件必须能直接运行不得留 TODO。 - 禁止为了凑覆盖率而编写无效断言。 - 需要模拟外部依赖时优先使用框架内置工具。 - 如果函数没有返回值测试其副作用或调用行为。 ## 参考文件 - 模板: reference/test-template.md - 风格: reference/testing-style.md注意看这份文档的几个设计点它明确写了输入是什么模型不会反复问你执行步骤是编号列表模型会按顺序执行质量约束是硬性的模型不会偷懒。这三点就是技能包和普通提示词之间最大的差异。3. 从零搭建整套Skills工作流3.1 先诊断自己的高频任务搭建技能包之前先花半小时做一次任务盘点。我把自己的开发工作切成几个大块写代码、写文档、做审查、查问题、做发布。每一块再往下拆找出重复性最强、规则最明确的小任务。拿我自己的情况举例子。写代码这块我每周要写二三十个函数。每次写新函数时都要裁判一下命名是否清晰、是否要加类型标注、要不要写 docstring、错误处理到什么粒度。这些规则我在脑子很清楚但写的时候总会偷懒。整理成代码生成技能后模型每次都会提醒我带上这些细节。做出诊断后按“频率 x 收益”排序。我的排序建议是代码审查优先做因为审查涉及的标准特别多人工做又特别累单元测试生成其次规则相对清晰文档生成排第三因为不同文档类型差异较大需要多个技能包覆盖。一个初期的技能包不需要做得完美先让它能跑起来再通过反馈迭代。花太多时间在第一次就做到完美会拖慢整体进度。技能的迭代逻辑和软件一样完成比完美重要。3.2 把任务拆解成可复用的子能力有了任务清单后开始设计技能包的边界。这是最容易出错的一步。很多人会按“任务”来定义技能而不是按“能力”来定义。任务和能力的区别在于可复用性。“写一个登录接口”是任务“设计一个带鉴权的接口”是能力。前者只适用于登录场景后者可以复用到所有接口开发。按能力来切技能包你会得到一组粒度更细、可组合的积木。登录接口开发可以用“接口设计 鉴权设计 代码生成”三个技能组合完成优雅且每个技能都能独立复用。子能力拆分的标准是单一职责。一个技能包不要既做代码生成又做代码审查这俩关注点完全不同。代码生成要发散尽量覆盖所有分支代码审查要收敛挑毛病找风险。混在一起模型会在生成模式与审查模式之间来回切换两边都做不好。还有一种拆分维度是按角色视角切分。比如“编写安全代码”技能关注开发视角“安全审计”技能关注攻击者视角。两者面对同一个代码库但关注点完全相反。你做审查时肯定不希望模型站在开发者的立场来自圆其说而是希望它站在攻击者的角度去找漏洞。3.3 版本管理与质量验收技能包要版本化。我在技能包里维护了一个自己的版本管理文件记录了每次改了什么、为什么改。你不需要引入特别复杂的工具一个简单的 changelog 文件就够了。# changelog.yaml - version: 1.1.0 date: 2025-06-12 changes: - 增加“数据一致性”审查维度 - 修复脚本在 Windows 路径下失效的问题 - 补充 SQL 注入检查示例每次改动技能包都要做一次完整的回归测试。技能的质量验收我建议用这五个维度第一是完成度技能是否按照 SKILL.md 的步骤完成闭环第二是格式正确性输出是否符合定义的格式第三是约束遵守度是否违反任何写在质量约束里的条款第四是稳定性同样输入跑三次输出差异大不大第五是鲁棒性换个说法描述任务技能是否还能被正确触发。为了能反复测试我准备了一小组固定的测试输入每次改完就全部跑一遍。这样技能包的任何回退都能第一时间被发现。这个做法让技能包的质量管理走向了工程化心里踏实很多。3.4 使用与调用方式技能包的使用方式取决于你用了哪类客户端。一种是把技能包目录配置到客户端的技能目录中模型会自动扫描并加载。另一种是手动指定直接在对话里用“技能路径 任务描述”的方式触发。我更推荐自动配置。手动指定的问题在于它要求你自己记住每个技能的路径和名称一旦技能多了就容易漏。自动加载还带来了一个新的能力模型可以“组合技能”。比如我现在有一个“安全审计”技能它会按类别输出问题清单但我并不满足于此想让它直接给出修复方案所以我把“代码修复”技能的调用也写进了审计步骤里让两个技能串成一条流水线。这里有两件值得注意的事情。第一技能包的 description 字段是触发匹配的关键不要写得过于宽泛。第二技能描述里如果明写了“当用户说X时使用”模型会更容易做匹配描述太含糊模型可能会选择不加载技能直接凭默认能力回答。4. 常见问题与排查技巧4.1 技能不生效的典型原因我踩过的最常见的坑是模型没有真正读到技能包的内容。你感觉自己配好了但输出完全没有体现出技能的约束。排查顺序是这样的先确认技能目录是否被主程序扫描到再看 SKILL.md 的元信息描述是否足够明确继续检查 SKILL.md 中是否出现角色冲突最后用无技能和带技能的同一输入各跑一次做对比。我自己遇到过一次很迷惑的情况明明配置正确部分会话能用技能包部分不行。排查了半天发现是目录名大小写不一致。在大小写不敏感的文件系统上没问题换到严格区分大小写的环境后就玄学失败了。所以从一开始就统一用小写加连字符的目录命名。另一种“不生效”是部分生效。模型加载了技能但输出格式没有完全按 SKILL.md 来。这种情况通常是因为 SKILL.md 里的约束写得不够具体。你把“输出审查报告”改成“输出包含表格、严重级别列、修复建议列的报告”模型照做的概率就高得多。模型不是不听话是给它的指令太含糊。4.2 让模型长期用你的Skills而不是忽略它在使用中你会发现一个矛盾技能越多模型越倾向于忽略部分技能特别是在上下文拥挤时。怎么让技能更被“重视”这背后其实有一套和上下文工程相关的取舍。我的经验是控制每个技能包的知识体积。技能包里的参考文件越多、越长模型越倾向于“挑重点”而不是“全照做”。把参考文件精简到最小可用程度每条保留一句结论和一个例子。另外把最关键的约束写到 SKILL.md 的前半部分让它尽早被读取重要指令放在靠后的位置说被遗忘的风险更大这不是胡猜的Transformer 架构对中间部分内容的“记忆力”普遍弱于开头和结尾。还有一个小技巧在输出格式中预留固定字段。比如代码审查报告强制输出时带上“审查标准版本”这样你只要一看到报告没有这个字段就知道技能没被执行。这比读完整段内容去判断是否生效要快得多也让模型把技能包当作真正的流程来执行而不是背景参考。4.3 同步与团队协作的坑技能包一旦开始多人共用就会遇到同步问题。我见过团队里最混乱的场景是张三更新了技能包李四还在用旧版本两个人审查标准不一致结论自然也打架。解决方式有两种一是用集中式仓库来管理技能包每次更新走 review 流程二是给技能包内部加版本协商机制让 SKILL.md 里写明本技能适用于哪类任务、不适用于哪类任务。这个“不适用”字段非常有用。比如我的 code-reviewer 技能包里明确写了本技能仅适用于后端服务代码审查不适用于前端样式审查。这样一来当有人拿前端代码来触发这个技能时模型会明确提示技能不匹配而不是硬着头皮输出一个质量低下的审查结果。另一个协作相关的问题是权限边界。技能包可能包含公司私有规范、内部工具路径等敏感信息分享给外部时要慎之又慎。我建议在共享前做一次技能包内容扫描把内部路径、专有信息全部替换成占位符。很多人会忽略这一点以为技能包只是“给 AI 看的提示词”不涉及敏感性问题但在实际环境中技能包恰恰可能成为最容易被忽略的信息外泄渠道。5. 进阶方向5.1 依赖管理与外部工具联动当技能包数量超过十个你会发现自己开始需要管理依赖关系了。某个技能可能在执行时需要用到另一个技能的产物或者需要调用外部脚本和命令行工具。我在一个数据清洗技能包里写了一小段调用说明指定执行前先检查数据目录是否存在、是否安装了依赖库如果缺少依赖要中止并给出安装指引。这样写不是因为模型不知道装依赖而是为了让它明白“你的任务是清洗数据不是装环境”避免它把时间耗在无关的事务上。还有更复杂的联动方式技能包内带可执行脚本。我在一个日志分析技能里放了一个 tiny 的解析脚本SKILL.md 里写了运行方式和预期输出格式。模型在执行时会调用脚本拿真实数据跑分析然后基于脚本输出做结论推断。这一步把技能从“文本参考”提升到“工具链”实用性大幅提升。技能包和外部工具联动时有一个原则工具是用来降低模型认知负担的不是用来增加负担的。如果引入一个工具反而要模型花更多精力去学习怎么用、怎么排错那这个工具就不要放进来。工具是为了让模型把精力放在它更擅长的判断和总结上而不是替代它做它做不好的“精确计算”。比如数学推导、太长的文本拼接、定时任务这类事情交给脚本确实比让模型直接做要靠谱得多。5.2 评估与迭代闭环技能包需要持续迭代不然会缓慢退化成“死文档”。我维护技能包的习惯分三块记录版本、收集失败案例、定期回顾。收集失败案例特别重要。日常使用技能的过程中凡是遇到输出不符合预期的情况不要只改对话让它重来而是要把这个失败案例记录到技能包目录下的 failures 文件里。然后去分析是技能定义有问题还是模型行为有随机性还是任务边界本来就不清晰。这个反馈闭环让技能包和实际使用情况保持同步一周下来你就能明显感受到质量的提升。定期回顾的节奏我选择每两周一次。把技能列表从头扫一遍标记出那些在过去两周内一次都没被触发过的技能。命中的技能保留没被触发的要判断是使用频率真的低还是描述写得太差模型从没匹配上。多数时候原因是后者那就改描述。少数情况下技能确实没有存在价值就把它归档不强行留着凑数量。技能包的数量不是指标匹配度和使用率才是。一个团队如果维护了几十套技能但日常只有两三套在滚动更新这个体系迟早会变成一件摆设。保持小、保持活跃、保持迭代是技能体系能长期发挥作用的唯一路径。5.3 让技能包具备复用与组合能力做到这个阶段你会发现技能包开始展现出“语言”的特性你可以用它们来组合更复杂的工作流。拿代码交付场景举例一条完整的流水线是先由“需求拆解”技能把业务需求转换成技术任务再由“接口设计”技能产出接口文档接着“代码生成”技能把接口文档变成实现“测试生成”技能自动补测试“代码审查”技能在交付前做一轮把关。这条流水线里的每一个技能都是独立维护的但它们之间通过标准输入输出自然衔接。你不需要用一个巨大的、臃肿的技能包覆盖所有环节只需要定义好上游输出和下游输入之间的约定让模型按约定流转。这种组合能力和编程中的函数组装非常相似——每个函数做一件清晰的事情函数与函数之间通过参数和返回值对接。我在实践中踩过的坑是技能之间的“交接文档”容易被忽略。模型做完前面一步后如果自动进入下一步它需要一份明确的中间产物规格比如要求它输出的接口文档必须包含完整的字段名和类型定义。否则下一步的代码生成技能就拿不到高质量输入。这个衔接契约要在前一个技能的输出约束里写清楚不能只靠下一个技能的输入描述来兜底。结尾用 skills 体系这段时间我最大的体会是真正的效率提升不是让模型一次性干完一个大活而是把大活拆成一套可以被稳定执行的流程积木。那些看似繁琐的 SKILL.md 编写、测试用例维护、更新日志管理本质上是在给自己的知识库做重构——把散落在聊天记录里的隐性经验变成结构化、可积累、可传承的显性资产。最后再分享一个小技巧当你新建一个技能包时不要只写你希望模型怎么做一定花五分钟写下“什么情况下不要用这个技能”。边界感越清晰的技能包模型用起来就越准。这个五分钟的投入能在后面替你省下无数次“为什么输出又跑偏了”的排查时间。技能包的核心价值在于沉淀和复用。别贪多从自己重复次数最多的那个任务开始先做一个跑顺了再做下一个。
