你有没有过这样的经历让AI帮你做代码审查你把规则、检查项、输出格式在对话里写了一大堆它这次执行得不错下次换了个话题再切回来又全都忘光了。或者团队里几个人用同一个AI编程工具每个人给的指令风格完全不一样审查出来的结果五花八门根本没法统一。这就是Skill框架要解决的问题。简单说Skill就是把你反复使用的提示词、流程、约束条件打包成一个结构化的技能文件让AI在需要的时候自动加载、按规矩执行。我刚开始接触这个概念的时候也觉得这不过是“提示词模板的升级版”但实际用了一段时间之后发现它背后的设计思路、目录组织、触发机制和我想的完全不是一回事。这篇文章我从头到尾拆一遍包括怎么设计一个Skill、SKILL.md文件怎么写、怎么测试和调优以及我在实际项目中踩过的坑希望能帮你把这个框架真正用起来。1. Skill框架到底解决了什么问题先搞清楚它和普通提示词的区别1.1 没有Skill时AI编程最常见的四个痛点我刚开始用AI辅助编程的时候最头疼的就是“每次都要把话说一遍”。比如我想让AI按照团队规范做代码审查每次都要在对话里重新描述一遍规范而且稍微换一种说法它的执行标准就飘了。这个问题不是个例我观察下来大多数没有用Skill框架的人都会遇到下面几种情况。第一是上下文空间的浪费。每次对话里塞进去几百行规范说明、示例代码、输出要求这些内容其实每次都一样但AI每次都要重新阅读和理解。一个项目的上下文窗口就那么大真正用来理解项目结构和代码逻辑的空间被压缩了回答质量自然下降。第二是执行标准不统一。就算你这次把需求说得再清楚下次开新对话AI对“代码审查”的理解又回到了自己的默认状态。团队里如果每个人都用各自的表达方式那审出来的结果就是各说各话规范形同虚设。第三是经验无法沉淀。我经常会遇到一个半小时才调试好的复杂操作流程当时觉得很珍贵但关掉对话就没了。下次再遇到类似问题还得重新从零开始推导等于同样的坑反复跳。第四是自动化程度低。没有Skill的时候AI只会被动响应你输入的内容你得不断提醒它“先做A再做B最后输出C”。这其实是在手工模拟Skill机制但每次都模拟得不完整。1.2 Skill的工作原理SKILL.md是怎么被AI“看见”的Skill框架的核心是一个叫SKILL.md的文件这个文件里通过特定的YAML格式写上技能的元信息然后在正文部分详细描述这个技能的执行步骤。当你在对话中提出某个请求时AI编程工具会根据请求内容和Skill元信息里的描述做匹配一旦命中就会自动把对应的SKILL.md内容加载进上下文。道理其实不复杂你可以把它理解成一个“按需查阅的手册”。AI平时就像一个新来的同事你说什么它听什么但它不知道你们团队的“潜规则”。Skill相当于把这些潜规则写成了手册放在它伸手就能拿到的地方。它需要处理代码审查时就翻到“代码审查”这一页需要写提交信息时就翻到“提交信息”那一页。不用把整本手册都背下来用到哪页查哪页。这种按需加载的设计还有一个很实际的好处就是省上下文。Skill文件本身写得再长只要当前任务不触发它就不会占用对话窗口。只有真正需要的时候才加载用完也不会长期占据空间。这一点在长会话里特别明显我试过用Skill之后同样一个复杂任务上下文消耗能节省差不多三成。2. 创建Skill之前先想清楚这三件事再动手2.1 命名和描述怎么定你的SKILL.md能不能被触发全看这一下很多人第一次写SKILL.md把精力全放在正文上结果写完发现AI根本不触发或者触发了但处理得不对。问题多半出在最上面的元信息部分。先来看一个标准的SKILL.md头部长什么样。这类文件通常以三个短横线开头里面包含几个关键字段然后在短横线下面是正文内容。--- name: code-review description: 对指定代码文件进行规范的代码审查检查可读性、性能隐患、边界情况与安全问题按严重程度输出问题列表。当需要评审代码质量、寻找潜在Bug、准备Code Review材料时使用本技能。例如帮我审查一下src/utils/auth.ts、这段代码有什么问题吗。 ---这里有几个细节值得说。第一个是name字段尽量用简短的小写字母加短横线比如code-review、unit-test-generator、commit-message-writer。不要用带空格或中文的长名字AI在匹配的时候更容易出岔子。第二个是description字段这才是决定能不能触发的关键。我见过很多人只写一句“用于代码审查”这种描述太弱了。一个好的description要包含三层信息这个技能做什么、在什么情景下用、给一两个触发示例。比如上面那段里加了“当需要评审代码质量、寻找潜在Bug、准备Code Review材料时使用本技能”后面还给了两个输入示例。这样AI在理解用户请求的时候匹配的准确率会高很多。我自己调试的时候总结出一个规律描述里最好直接放入用户可能会说的原话片段。比如用户经常会说“帮我看看这段代码”或“review一下这个PR”这些短句直接写进description里命中率比抽象描述高。触发机制本质上是做语义匹配你的描述越接近真实对话的习惯用语匹配就越准。2.2 Skill的正文结构让AI能“照着执行”而不是“参考一下”正文部分很多人会犯一个错误就是写得太像给人看的文档大量使用“我们应当”“请务必注意”这种话。AI不是人它需要的是明确的操作指令。我建议正文采用下面这种结构一层一层约束它的行为。第一部分是角色与目标用一两句话定义一个清晰的执行人设。比如“你是一位有十年一线开发经验的高级工程师负责对代码做严谨的审查”简洁明确即可不用写太多铺垫。第二部分是执行步骤把整个流程拆成有序的步骤让AI无论处理什么输入都按这个顺序走。代码审查这个技能我就拆成四步先通读代码理清结构和职责再按规范逐项排查然后输出问题清单最后给出整体评价。每步下面再补充具体检查什么比如可读性看变量命名和函数拆分性能看循环嵌套和重复计算安全看输入校验和权限控制。第三部分是输入输出格式的定义。AI最怕模糊的输出要求你得告诉它最终回答用什么格式。比如我要求审查结果按“严重问题”“一般问题”“建议优化”三个等级输出每个问题都标注所在函数名、行号、问题类型和具体修改建议。预定义好输出结构后续处理结果就很省力。第四部分要写清楚边界也就是什么情况不要动用这个技能。比如只审查AI能看到的代码不审查外部依赖包的内容。边界写清楚AI才不会过度发挥。2.3 哪些内容不适合做成Skill别把一次性任务硬塞进去和初学者想法相反的是不是所有任务都适合做成Skill。我自己总结了几类不适合的场景帮你提前避雷。第一类是涉及大量实时数据的任务。比如“检查某个线上服务的当前状态”这种任务依赖实时信息但Skill里存的规则是静态的你没法在里面预设今天服务跑得好不好。还有“统计本周新增的Bug数量”也一样这类就老老实实在对话里提问不要做进Skill。第二类是高度依赖具体项目上下文的任务。Skill是通用的技能包适合那种无论放到哪个项目都能用的流程。但如果你写的Skill里全是某个项目专有的模块名、类名、业务术语那它换个项目就完全失效了。这种内容应该放在项目文档里或者直接对话时提供不适合放Skill。第三类是一次性的任务。比如“帮我把这段代码改成用某某框架重写”这种你大概率不会重复做做成Skill就是浪费。第四类是过于复杂的任务。一个Skill的正文最好控制在一个核心流程以内。如果你发现自己写了五百行又是一个长流程又是十几个子步骤建议拆成多个关联的Skill而不是硬塞一个。AI对超长指令的执行效果会明显下降越短越聚焦执行力越强。3. 实操全过程从零开始打造一个代码审查Skill3.1 目录结构怎么搭提前规划好技能库的组织方式在动手写SKILL.md之前先把目录规划好。Skill框架支持多级目录你可以把所有技能放在一个总目录下再按用途分成子目录。以我的个人技能库为例大致是这样的结构skills/ ├── review/ │ ├── code-review/ │ │ └── SKILL.md │ └── pr-description/ │ ├── SKILL.md │ └── examples/ │ ├── good-pr.md │ └── bad-pr.md ├── generate/ │ ├── unit-test/ │ │ └── SKILL.md │ └── commit-message/ │ └── SKILL.md └── refactor/ ├── extract-function/ │ └── SKILL.md └── rename-symbol/ └── SKILL.md这样组织有几个好处。第一是每个Skill都有清晰的路径和命名空间就算名称重复也不冲突。第二是如果你想让AI有优先级顺序可以通过目录结构来控制。第三是可以在Skill目录里放辅助资源比如示例代码、模板、参考文档这些资源SKILL.md可以通过相对路径引用。存放位置这块务必注意不同AI编程工具对Skill目录的识别方式不一样有的是项目根目录下的特定文件夹有的需要在配置里手动指定目录路径。我用得比较多的一种方式是把skills目录放在项目根目录下这样所有项目成员拉取代码后都默认可用。放进目录后一定要检查一下工具的配置文件确认扫描路径是否覆盖了你的skills目录。3.2 编写SKILL.md一个可以直接抄的代码审查技能前面铺垫了这么多理论现在把一份完整的SKILL.md写出来看看。下面这份是经过我多次调整、实际跑过很多轮审查的版本。你们可以把内容复制过去按自己的需求修改。--- name: code-review description: 对指定代码文件进行规范的代码审查检查可读性、性能隐患、边界情况与安全问题按严重程度输出问题列表。当需要评审代码质量、寻找潜在Bug、准备Code Review材料时使用本技能。例如帮我审查一下src/utils/auth.ts、这段代码有什么问题吗、review一下这个文件。 --- 你是一位有十年一线开发经验的高级工程师负责对用户指定的代码进行严谨、细致的代码审查。 请严格按照以下步骤执行审查 1. 定位代码确认用户指定的文件或代码段通读全部代码梳理代码的结构和主要职责。如果代码较长先总结整体逻辑再逐个模块审查。 2. 逐项排查按以下维度检查代码质量和风险 - 可读性变量命名是否表意清晰、函数是否过大、逻辑分支是否容易理解 - 正确性是否存在边界条件遗漏、空值未处理、类型误用、异步时序问题 - 性能是否有不必要的重复计算、可以提升的算法复杂度、过深的循环嵌套 - 安全性是否有未经过滤的输入拼接、不安全的文件操作、缺少权限校验 3. 输出问题清单按严重程度分类格式如下 **严重问题**可能导致错误结果或安全漏洞 - [函数名/位置] 问题描述具体到代码行号和修改建议 **一般问题**影响代码质量或可维护性 - [函数名/位置] 问题描述具体到代码行号和修改建议 **建议优化**个人经验层面的改进想法 - [函数名/位置] 问题描述具体到代码行号和修改建议 4. 整体评价用两到三句话总结这段代码的整体质量、主要风险点和是否适合合入主干。 注意以下边界 - 只审查用户指定的代码范围不要主动扩大到未指定的文件 - 如果用户没有指定具体代码先把代码片段或文件内容找出来再审查 - 对依赖库内部的实现不做评价只评价本项目内的代码这份文件看起来不长但关键信息都覆盖了。我在正文里特意用了“按以下维度检查”“输出格式如下”这种命令式语言因为AI对明确指令的遵循度明显好于建议式的措辞。3.3 测试与微调怎么确认你的Skill真的有效写好SKILL.md把它放到目录里这只是开始。接下来要做的是测试这一步很多人会跳过但它是确保Skill真正可用的关键。第一轮先做单元测试。我一般会新建一个干净的对话窗口用description里的触发示例作为输入比如直接输入“帮我审查一下src/utils/auth.ts”然后观察AI是不是自动加载了技能。怎么判断它加载了呢看它的回答风格。如果它开始说“我将按照代码审查的标准流程进行检查”那说明技能被触发了。如果它只是笼统地回答“这段代码看起来不错”那基本可以确定Skill没加载上。第二轮做效果测试。用一段故意写了一些常见问题的代码比如有一个未处理的空指针、一个简单但低效的循环、一个字符串拼接的SQL语句然后让AI审查看它能不能把这三个问题都找出来并且按预设格式输出。我一般会准备两三个不同难度级别的测试代码从简单到复杂都测一遍确保不是因为测试代码太简单才碰巧及格。第三轮做边界测试。故意用一些模糊的表述比如“帮我看看代码怎么样”看它会不会错误地触发了别的Skill或者做得太过连无关文件都审查了。边界测试还有一个目的就是确认没触发的时候AI不会自作主张用Skill的规则。测试完之后基本都要微调。我自己的经验是最多的情况是description写得太宽泛导致很多不该触发的场景也触发了。解决办法就是加负向描述比如“如果只是修改注释、调整格式不要使用本技能”。另一种常见问题是输出格式不稳定AI偶尔会漏掉“严重问题”这个分类这时候在正文里把这个分类单独强调一遍或者把输出格式部分加粗标出来重复率就会降下来。4. 把Skill用出水平调试、复用与团队级落地4.1 调试技巧技能没生效从这几个地方逐层检查在你已经把Skill写好的情况下如果AI完全没有按Skill的思路执行我的排查顺序是这样的。先确认文件格式。检查文件名是不是严格叫SKILL.md大小写都不能错。有的工具不认SKILL.MD或者认skill.md具体以工具文档为准这个必须确认。再看第一行是不是三个短横线开头YAML元信息有没有写对。YAML解析报错是静默的有时候AI根本没读到元信息技能自然不会被匹配。再查路径。确认SKILL.md所在目录是否在工具配置的搜索范围内。这里有一个很容易忽略的点如果你的技能目录是在.gitignore里面那AI扫描项目文件的时候可能直接把这个目录忽略了技能就藏起来了。我遇到过一次排查了很久才发现是这个问题。然后看描述是否清晰。你可以在对话里直接问AI让它列出可用的技能清单看它能不能说出你的Skill名字。如果连列都列不出来说明匹配逻辑就没走到。这种时候就要改description加入更贴近用户原话的触发词。最后还有个统筹排查检查是否有多个Skill的description互相重叠。比如你同时有一个code-review和一个security-check的技能两个的描述里都写了“检查代码安全问题”那你触发审查的时候AI可能同时加载两个技能出现指令争夺。我的建议是每个技能描述里的触发词尽量差异化避免重叠区域。4.2 复用经验把Skill从一个项目迁移到另一个项目Skill文件本身是纯文本迁移起来最理想的状态就是复制粘贴。但我在实际迁移中遇到过几个要注意的坑。第一个是路径引用问题。如果你的SKILL.md里引用了examples目录下的参考文件用了相对路径迁移后这个相对路径必须保持完整。比如pr-description这个技能引用了examples/good-pr.md你复制技能目录的时候得把examples一起带上否则引用就断了。第二个是对项目特定术语的依赖。有些技能写着写着就把当前项目的专业词汇混进去了比如某个微服务名、某个内部库的API风格。迁移到新项目后这些词对AI来说就成了无意义的噪音。所以我每次迁完都会通读一遍正文把项目特有名词替换成通用表述。第三个是优先级和顺序的问题。多技能场景下AI的执行顺序可能有讲究比如你要求先跑单元测试生成再做代码审查这两个Skill之间没有天然的先后关系AI可能会随意选择。解决办法是在一个Skill里的执行步骤中写明前置依赖比如“如果代码审查结果存在严重问题不要继续执行单元测试生成直接输出审查报告”。这种隐性关联写清楚迁移后仍然有效。4.3 团队级落地把个人经验变成组织资产Skill框架真正发挥威力是在团队协作的时候但这需要一定的管理方法。我帮一个小团队落地过一整套流程说几个关键点。建立技能库评审机制。最开始团队里每个人都写自己的Skill质量参差不齐。后来我们约定每个新Skill要过一遍评审主要看看命名是否规范、description是否容易触发、正文有没有写清楚边界。评审通过后放进共享目录由版本控制系统管理所有成员拉下来就能用。把已有文档转成Skill。团队通常积累了大量经验文档比如编码规范、部署清单、Bug排查手册这些内容一般躺在文档系统里没人看。我的做法是把高频使用的文档先转成Skill比如“数据库连接排查手册”转成一个troubleshooting技能让AI在遇到连接问题的时候自动按手册里的顺序排查。效果很明显新人减少了很多无效提问。以季度为单位维护技能库。我们每季度审视一遍全部Skill删除半年没人触发过的合并功能重叠的更新描述里过时的示例。不然等到技能库积累到几十个的时候频繁重叠的触发逻辑会让AI整体的响应速度变慢。5. 常见问题速查表照着排查十分钟定位问题问题现象可能原因解决方案AI完全不按Skill执行文件夹或文件名不对检查文件是否为SKILL.md大小写确认无误YAML元信息解析失败检查yaml格式确认字段冒号后面有空格Skill偶尔触发偶尔不触发description里的触发词覆盖面不足在描述里加入更多用户原话示例配合负向词排除干扰与其他技能描述重叠调整各技能的描述让触发场景差异化AI读取了Skill但输出格式不对正文格式描述不够强制用“必须按以下格式输出”等命令语句重复强调模板正文过长导致重点丢失精简正文把核心步骤控制在五步以内格式模板单独放置Skill内容被AI忽略技能目录被版本忽略了检查.gitignore和相关配置技能文件引用路径断链检查正文里引用的辅助文件是否存在路径是否正确新开对话后Skill失效工具只加载项目级目录个人级目录没有配置根据工具情况把Skill放进项目根目录下或配置中声明多条Skill同时加载描述里的触发词覆盖了同一种请求精简描述范围为每个技能划定唯一场景迁移到其他项目后Skill表现变了正文里残留了旧项目专有名词迁移时通读正文把项目特有内容替换为通用表述这个表是我实际使用中高频踩坑的总结基本覆盖了大部分初次使用Skill框架的人会遇到的问题。有一条原则可以记住当Skill没生效的时候先排查“AI有没有真的看见这个文件”再看“看到的描述是否足够匹配”。写在最后的一点心得Skill框架用到现在我自己最大的感受是它逼迫你把自己的工作流程显性化。以前我脑子里很模糊地觉得“应该先看看代码再改”但写成Skill之后被迫把“怎么看”“从哪些维度看”“看完之后输出什么”都定义出来。这种定义的过程本身就是一次能力梳理就算SKILL.md不被AI执行光是对着写一遍也能帮自己理清思路。我在几次带新人的过程中发现把复杂任务的Skill直接交给新人比让他们看文档、看代码快得多。AI相当于把老师傅的思考过程复刻了一份随时可以被调用。还有一个很实用的小技巧我会在Skill正文里留一个“修订记录”小节记录最近一次修改了什么、为什么改。这样过了一个月回头看能知道当时调整的动机不至于改着改着忘了初衷。这个习惯是我踩了几次坑之后养成的有一次我把审查输出从两个等级改成三个等级结果忘了通知团队成员导致大家以为AI抽风。加了修订记录之后再也没出过这种混乱。Skill框架不会让AI变得更聪明但它能让AI像一个稳定的老员工一样每次都按你的标准做事。你要做的就是花一个下午把你最常让AI做的那些事情认真写成技能文件这一下午的投入后面会以倍数的形式回报你。