企业官网建设流程全解析

你有没有过这样的经历：让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. 实操全过程：从零开始打造一个代码审查Skill

3.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. 常见问题速查表：照着排查，十分钟定位问题

这个表是我实际使用中高频踩坑的总结，基本覆盖了大部分初次使用Skill框架的人会遇到的问题。有一条原则可以记住：当Skill没生效的时候，先排查“AI有没有真的看见这个文件”，再看“看到的描述是否足够匹配”。

写在最后的一点心得

Skill框架用到现在，我自己最大的感受是：它逼迫你把自己的工作流程显性化。以前我脑子里很模糊地觉得“应该先看看代码再改”，但写成Skill之后，被迫把“怎么看”“从哪些维度看”“看完之后输出什么”都定义出来。这种定义的过程本身就是一次能力梳理，就算SKILL.md不被AI执行，光是对着写一遍，也能帮自己理清思路。我在几次带新人的过程中发现，把复杂任务的Skill直接交给新人，比让他们看文档、看代码快得多。AI相当于把老师傅的思考过程复刻了一份，随时可以被调用。

还有一个很实用的小技巧：我会在Skill正文里留一个“修订记录”小节，记录最近一次修改了什么、为什么改。这样过了一个月回头看，能知道当时调整的动机，不至于改着改着忘了初衷。这个习惯是我踩了几次坑之后养成的，有一次我把审查输出从两个等级改成三个等级，结果忘了通知团队成员，导致大家以为AI抽风。加了修订记录之后，再也没出过这种混乱。

Skill框架不会让AI变得更聪明，但它能让AI像一个稳定的老员工一样，每次都按你的标准做事。你要做的就是花一个下午，把你最常让AI做的那些事情，认真写成技能文件，这一下午的投入，后面会以倍数的形式回报你。