写Skill这事儿现在有点两极分化。拿Claude、Codex这类工具的人要么是第一次见到SKILL.md不知道怎么用要么是已经写了十几个但总觉得差点意思——模型经常不按套路出牌指令一长就晕换了场景就得重写。如果你刚好卡在“能写但不好用”这个阶段这篇文章就是给你准备的。上一篇我聊的是Skill的基础玩法它是什么、文件结构长什么样、一个能跑的Skill需要哪些基本要素。这篇我们直接上强度聊高级玩法。我会把Skill的底层逻辑重新拆一遍然后是工程化设计的完整思路、高级编写技巧、三个实战场景的完整拆解最后是几组我踩过的坑和排查方案。目标是你看完之后能独立设计出稳定、可复用、真正提升效率的Skill而不是简单的“提示词搬运工”。1. 先想明白Skill到底解决什么问题1.1 Skill、Agent和普通提示词的区别很多人分不清这三者的边界结果就是Skill写得像提示词Agent用起来像Skill最后什么都干不好。我用一个不太严谨但很好用的类比来解释。普通提示词是一段对话指令你告诉模型“现在做X”模型做完了就结束了没有任何记忆和上下文。Agent是一个调度者它自己决定先做什么后做什么遇到问题会自己调整计划。Skill是介于两者之间的东西——它是一套打包好的、有结构的能力模块里面包含指令、示例、约束和可能的辅助文件。打个比方普通提示词是让一个厨师“做一道红烧肉”Agent是让一个厨师“负责今晚的宴席”Skill是给厨师一本《川菜标准菜谱》——里面写清楚了原料配比、火候控制、装盘标准厨师照着执行就行。为什么这个区别很重要因为它决定了你的设计思路。你写提示词时可以随意但写Skill必须严谨因为在Agent的工作流里Skill是要被反复调用的皮实程度直接决定了整个流程的稳定性。1.2 Skill真正擅长解决的典型场景基于我自己的实践Skill最擅长解决的是三类问题。第一类是重复性高、规则固定的任务。比如从网页里抽取结构化数据、把会议记录转换成待办事项、把客户信息整理成标准格式。这类任务的共性是步骤清晰、输出格式固定、不需要太多创造性。第二类是流程复杂、需要分步执行的任务。比如一份专利检索分析你需要先理解技术方案再拆解技术特征然后构建检索式最后去数据库检索并整理结果。这种任务如果只用一段提示词模型很容易中途跑偏——要么把检索式写得很业余要么直接跳过某些关键步骤。用Skill可以把整个流程固化成标准动作。第三类是知识密集、需要大量上下文注入的任务。比如前端开发里的Vue最佳实践或者数学建模里的常见算法选型。这类任务你没法每回都手写一遍规范但你也希望模型每次都能按规范执行。把规范和决策树写进Skill里等于给模型配了一本随身的参考手册。我见过不少人在这个阶段选择直接堆提示词效果往往是一开始觉得“哇AI好聪明”用一段时间就发现输出质量很不稳定。原因很简单提示词没有结构没法约束模型的行为边界。Skill解决的恰恰是这个结构问题。2. Skill工程的完整设计与文件组织2.1 目录结构设计的核心原则上一篇文章讲过SKILL.md是整个Skill的核心入口但真正好用的Skill绝不是一个单文件能搞定的。我建议按这个标准结构来组织my-skill/ ├── SKILL.md # 主入口定义Skill的职责、使用场景、整体流程 ├── references/ # 参考资料领域知识、规范文档、代码片段 ├── scripts/ # 辅助脚本数据处理、格式转换等 ├── assets/ # 静态资源模板、示例文件 └── rules/ # 细分规则按场景拆分的约束条件这个结构模板看起来好像没什么特别但实际执行力非常强。核心原则有三个。第一个原则是入口文件要轻。SKILL.md只负责定义“这个Skill什么时候用、整体流程是什么、关键规则有哪些”不要把所有细节都塞进去。很多人写第一个Skill的时候一口气写了500行最后模型根本处理不过来。轻量入口的好处是模型每次调用都会完整读取SKILL.md如果文件太大反而干扰模型的注意力。第二个原则是细节下沉到references。比如你做的是一个论文检索Skill那检索式的构建规则、筛选标准、字段含义这些不需要全部写在SKILL.md里而是放到references/里让模型在需要的时候再查阅。第三个原则是保持相对路径引用。所有引用的文件都用相对路径这样整个Skill目录可以整体拷贝、移动到任意位置不会因为路径失效而罢工。2.2 SKILL.md的撰写流程和结构模板我写SKILL.md一般遵循这个步骤。先把技能的目标写清楚——一句话说清楚这个Skill是干什么的。然后写适用场景和禁用场景这个很多人容易忽略但特别重要因为不确定边界会让模型在不该用的时候强行套用。接着逐步拆解执行流程每一条都写清楚行动的触发条件和预期结果。最后补充规则和约束。给你一个可以直接参考的模板--- name: patent-analysis description: 专利检索分析从技术方案描述到检索式构建再到结果筛选与分析报告生成 tags: [专利, 检索, 分析] --- # 专利检索分析 ## 什么情况下使用本Skill - 用户提供技术方案需要检索相关专利 - 用户需要查询现有技术、评估专利新颖性/创造性时 - 用户提供专利号需要分析其技术方案和保护范围时 ## 什么情况下不使用本Skill - 用户没有明确的技术主题只是泛泛提问 - 用户需要处理专利法律事务如无效宣告、侵权诉讼时 ## 执行流程 ### 第一步确认技术主题 1. 阅读用户提供的技术方案提取核心技术特征 2. 确认关键词及同义词、近义词 3. 与用户确认理解是否准确避免检索方向跑偏 ### 第二步构建检索式 1. 根据技术特征确定IPC分类号和关键词 2. 参考references/retrieval-guide.md中的检索式构建规范 3. 输出初步检索式标注使用的数据库 4. 根据分母精度、查全率需求调整逻辑运算符与截词符 ### 第三步筛选与分析 1. 阅读检索结果剔除明显不相关专利 2. 对相关专利进行技术方案对比 3. 整理分析结论输出报告注意这个模板里我用了YAML格式的frontmatter这是目前主流工具通用的头部信息格式。写了name和description模型就会更好地理解这个Skill的用途调用准确性会高很多。2.3 命名规范和版本管理技巧命名这事看似不起眼但影响的是长期的维护体验。我现在遵循这组规则Skill名称用英文小写加连字符比如code-review、>## 输入参数 - output_date_format: 输出日期的格式可选值 [YYYY-MM-DD, YYYY年MM月DD日, MM/DD/YYYY]默认值 YYYY-MM-DD - include_time: 是否输出时间true/false默认 false这样用户在调用时就可以灵活指定格式不用每次改代码。看似是个很小的改动但如果你要维护几十个Skill参数化能省下大量时间。我做参数化设计时还有一个经验陷阱要提醒你参数说明里的可选值一定要写清楚并且要写默认值。模型在没有明确说明时通常会自己“从上下文里猜”这往往是输出不符合预期的根源。把所有参数的取值范围和默认值写清楚能大幅提高召回率。3.2 多步编排拆成可独立校验的步骤复杂任务一定要拆步骤每步只做一件事并且可以在这一步结束时要求模型输出阶段性结果供你检查。我之前写过一个“学术论文摘要翻译”的Skill一开始全部写在一个Prompt里让模型“翻译摘要并保持学术风格”结果输出质量很不稳定有的把术语译错有的丢掉引用标识有的格式全乱。后来我改成多步编排步骤1识别原文的学科领域和术语表输出术语对照表 步骤2逐句翻译保留原有结构和引用编号 步骤3对照术语表检查译文标注不一致的地方 步骤4按目标期刊的格式要求整理输出每一步都要求模型先输出中间结果我检查无误后再进入下一步。质量明显上升而且出问题的时候很容易定位——是术语识别不对还是格式整理不对一眼就能看出来。多步编排的核心逻辑是你在每一道关口都设置了“检查点”模型跑偏的概率被压缩到最小。这和团队里做代码审查是一个逻辑你拆得越细越容易控制风险。3.3 条件逻辑与分支处理高级Skill还有一个重要特征是能够根据条件走不同的分支。例如你写一个“客服工单分类”的Skill需要这样处理## 分支规则 1. 如果工单标题含“退款”“退货”进入退款处理流程 2. 如果工单标题含“发货”“物流”进入物流查询流程 3. 如果工单标题含“投诉”进入投诉升级流程 4. 如果以上均不匹配标记为“其他”转人工处理写分支规则时关键词不要写得过于严格。比如“退款”和“退钱”是同一个意思如果你只写了“退款”没写“退钱”模型会在边缘案例上翻车。我一般会在规则后面加一条兜底指令“如果用户表述中包含任何与上述关键词含义相近的表述按对应分支处理。”这个兜底很重要它能消化掉语言表达的多样性。3.4 组合式Skill多个Skill协同的玩法单个Skill的能力总是有限的高级玩法里非常值得投资的是组合式设计。简单来说就是在一个Skill的执行流程里明确调用另一个Skill的处理结果或者让一个Agent在多个Skill之间切换。我举一个实际的例子。我平时写专利分析报告时有两个Skill一个是“patent-search”负责检索和筛选。一个是“technical-writer”负责把分析结论改写成规范的技术报告。在一个新的工作流里我让Agent执行“patent-search”得到检索结果然后把结果作为输入传给“technical-writer”来生成报告。这样两个Skill各司其职耦合很松任何一个Skill的升级都不影响另一个。你实现组合时要注意一个细节在SKILL.md里面最好用“外部依赖”一节明确列出“如果环境中已安装XX Skill优先调用它作为XX步骤的输入来源”。这样Agent在调度时就会主动去查找并使用而不是自己临时起意另写一套流程。3.5 反馈循环与自我校验最后一条高级技巧可能最反常识真正好用的Skill应该告诉模型“在输出之前先自己检查一遍”。什么意思呢模型在生成内容后往往已经处于“下班状态”不会主动审视自己的输出。但加了反馈循环之后情况会完全不同。我通常在SKILL.md的最后加一个“输出前自检”区块## 输出前自检 在输出最终结果之前请执行以下检查 1. 输出格式是否完全符合要求是否有遗漏字段 2. 所有数据是否经过计算或引用验证 3. 术语是否与references/term-base.md保持一致 4. 是否存在明显的事实错误或逻辑跳跃 如有问题请修正后再输出。这个技巧源自一个朴素的观察模型的能力本身并不差很多时候只是懒没有把“检查”这步纳入流程。你强制它做检查之后输出质量稳定得让人惊讶。尤其是做数据整理、格式转换这类任务自检能直接消灭一半以上的低级错误。4. 三个实战场景的完整拆解4.1 场景一专利检索与分析的Skill专利检索是我用得最多的场景之一因为它的流程非常成熟、规则性极强非常适合写进Skill固化下来。这个Skill我按照前面讲的多步编排来设计。第一步是“确认技术主题”模型需要提取用户描述中的核心技术特征并且输出关键词列表供用户确认。第二步是“构建检索式”这一步是重点因为专利检索式的表达非常讲究——要用好分类号、关键词、截词符还要考虑布尔运算符的优先级。我在references/retrieval-guide.md里放了一份详细的检索式构建指南包括常见IPC分类号、关键词扩展技巧、运算符优先级说明。第三步是“结果筛选与分析”模型需要根据摘要判断相关性排除明显不相关的专利并输出筛选理由。最后生成分析报告。实际运行效果非常稳定。一组专利检索任务原本要花3到4小时现在大概40分钟可以完成初筛剩下的时间用来人工审核和深入阅读重点专利。对于经常做专利相关工作的研发人员或者专利工程师来说这种Skill可以当作日常标配来用。4.2 场景二编程辅助与代码审查编程类的Skill可能是目前社区里最活跃的领域。我自己维护了两个一个叫“code-review”负责审查代码质量一个叫“refactor-helper”负责在不改变功能的前提下重构代码结构。“code-review”这个Skill在设计时我刻意没有把关注点放在“语法错误”上——语法错误的识别是模型的基本功不需要额外写Skill。我真正想让它做的是架构层面的审查模块间的耦合度是不是太高、有没有明显的重复代码、错误处理是否完善、有没有安全隐患。所以我写进references/里的是一套自定义的代码审查清单内容比通用代码规范要挑剔得多。比如“所有外部输入必须在入口处校验”“事务操作必须考虑回滚和幂等性”“日志记录不得包含敏感信息”。这相当于把你们团队多年积累的code review经验全部注入给模型。第一次运行的时候项目组同事还以为我安排了个资深工程师在旁边盯着看效果可以说相当惊艳。“refactor-helper”则要处理另一个方向的问题它需要判断哪些代码可以安全重构、哪些地方不能动。我在SKILL.md里明确写了禁用场景“如果当前代码存在未处理的异常分支或者函数过长且存在隐藏副作用不要自动重构先输出警告。”这个约束帮我避免了好几次危险的自动改动。4.3 场景三前端开发中的规范执行前端领域有个很有意思的痛点项目里明明有规范文档但开发的时候经常被忽略。虽然可以装ESLint、StyleLint之类的工具但很多规范软件工具检查不出来比如组件的命名规范、props的传递规范、状态管理的使用规范。这种“有文档但难执行”的痛点非常适合用Skill解决。我做过一个“vue-best-practices”的Skill把项目里沉淀下来的Vue最佳实践全部整理进去并且按照组件设计、路由管理、状态管理、性能优化四个维度组织。在references/里面每个维度都配了一份详细的规范文档和正反案例。有意思的是这个Skill和普通Lint工具配合起来能做到“硬规则交给工具、软规范交给AI”的互补状态。代码写完之后跑一遍ESLint处理硬规则然后让“vue-best-practices”跑一遍处理那些工具看不出来的设计层面问题。比如每个组件是否做到了单一职责、computed和watch的使用是否正确、数据流是否清晰。实测下来整个开发团队提交的代码质量有明显提升评审会议的争议也变少了。前端Skill有一点需要特别注意这类任务高度依赖具体的项目上下文。所以我在Skill里留了一个参数project_context要求在调用时传入当前项目的技术栈和关键约束。没有这个上下文Skill输出的规范就容易是“正确的废话”。5. 常见问题与排查技巧实录5.1 使用现成Skill时常见错误类型很多人喜欢直接网上找一个现成的Skill来用但装上之后发现效果跟卖家秀完全不是一个东西。基于我观察到的现象最常见的错误主要有四类。第一类是执行结果太泛模型出来的东西全是套话没有实质性内容。这种情况通常是Skill本身的指令太宽泛没有给出具体的决策图或过滤标准。第二类是行为不稳定同一组输入每次都给出不同的结果。这种通常是SKILL.md的指令里有模糊表述比如“尽量”“适当”这类词太多模型每次理解的权重都不一样。第三类是格式混乱输出结构的字段经常缺失或错乱。一般是因为没有在Skill里明确输出模板也没有做自检。第四类是上下文泄露模型把不相关的历史对话信息带进了输出。5.2 排查与解决的具体方法面对这些问题我有一套相对固定的排查流程。第一步启用追踪和日志。大部分支持Skill的工具都有调试模式你把调用过程记录下来能看到模型每一步输出了什么。这一步极其有用因为很多时候你以为是Skill本身的问题结果是Agent的调度出了偏差。第二步检查SKILL.md的长度和复杂度。如果文件超过200行先考虑把细节下沉到references/。模型对超长指令的处理能力有限前200行以内的信息权重最高越靠后的内容越容易被遗忘。第三步把模糊词替换成可验证条件。把所有“尽量”“适当”“合理”这类词改成“如果……则……否则……”这种明确的条件分支往往立竿见影。比如“尽量保持简短”改成“如果输出内容超过500字请压缩至500字以内并保留核心论点”。第四步增加自检环节。在前面提到的“输出前自检”区块里把常见的问题列举出来让模型自己对照检查。这个方法成本最低收益却很稳定。5.3 一个容易被忽视的隐藏坑最后说一个特别隐蔽的问题我称之为“Skill的自嗨陷阱”。通俗地说就是一个Skill写得逻辑上完美自洽但放进实际工作流里根本用不上。为什么会这样因为很多人写Skill的时候是按“理想流程”来设计的但实际的工作流往往有各种约束。比如你设计了一个“会议纪要生成”的Skill要求先识别语音转写文本再生成摘要但你的会议系统导出的文本本身就带了很多噪声和重复内容模型的精力全被噪声消耗掉了生成的纪要质量就很差。解决这个问题的方法只有一个写Skill之前先花时间研究真实数据的长相。从实际场景里挑10个典型样本用它们来校准你的Skill规则和示例。这也是我坚持Skill要“养”而不是“写”的原因——它需要在一个真实的、有摩擦的环境里不断调试才能真正变成好用的工具。最后分享一点个人经验用了这么久的Skill我的体感是真正拉开差距的通常不是模型能力而是你对任务的拆解能力和对规则的表述能力。Skill写得好的人往往不在于他掌握多少技巧而在于他自己对这个业务有足够深的理解——他知道每个环节的风险点在哪里知道什么样的输出是可接受的知道什么时候该让模型自由发挥、什么时候必须严格约束。现在你做Skill的时候我建议从一个小而重要的场景入手先做一版能用的然后在实际使用中逐步加细节。别试图一步到位也别一看到效果不好就推倒重来。Skill是会“长”的你喂给它的每一次修正、每一个反例、每一条新规则都会让它变得更懂你。如果你现在手头就有一个反复在做但每次都要重新解释的流程那就是最适合变成Skill的对象。动手写一个吧用今天的思路你会发现AI能替你扛下的杂活远比想象中多。
