企业官网建设流程全解析

给AI编程助手装个“技能包”：聊聊我折腾skills文件夹的完整过程

最近一直在折腾给AI编程助手配“技能包”，也就是现在社区里很流行的skills概念。简单说，它就是用一套结构化的Markdown文件，把某个领域的高频操作、代码规范、常见坑位，提前喂给AI，让它碰到该场景时不再“临时发挥”，而是照着成熟方案来。这东西对用Claude Code、Cursor这类工具的开发者尤其刚需，也是我最近项目里实实在在涨效率的关键。这篇就把我从了解到落地完整的过程、原理、踩坑和最终方案都讲一遍，适合那些已经用上AI辅助编程、又不满足于“一问一答”，想让AI更懂自己项目套路的人参考。

1. 为什么给AI编程助手单独配一套skills，而不是全指望模型本身

1.1 从一次翻车说起

先说个真实场景。我那阵子在做公司内部的组件库维护，需要频繁给现有组件补单元测试。说实话这套组件的测试写法很固定：一个describe里套三四个it，事件触发走testing-library的userEvent，异步部分用waitFor断言，断言风格统一走jest-dom。这个套路我闭着眼都能写，问题是AI助手不行。

我换了三种主流工具试过，把需求说得再清楚，它第一版生成的测试代码总会有几个老毛病：断言方式跟项目现有代码风格不一致，错误地用了浅层渲染而项目里规定必须真实挂载，异步等待方式千奇百怪——有时候是sleep有时候是waitForTimeout，根本不是项目里的标准写法。我每次都得逐行改。

那时候我才想明白一个问题：模型参数里的“常识”跟“你项目里的具体规范”是两码事。指望模型自带你的团队规范，显然不现实。

1.2 底层逻辑：模型本身不是短板，上下文才是

后面我接触到了skills的概念，再回头琢磨这件事，才发现问题的本质是上下文工程。

大型语言模型的能力是固定的，你上一个Prompt它输出一个结果。同一个模型，你能不能让它输出高质量的结果，取决于你在上下文里给了多少“有效信息”。你要它写测试，它脑子里至少有一百种“写测试”的写法，但没有一种精确匹配你项目的写法。你指望靠一句话说清楚全部约束，这根本不现实。但是如果你在上下文里塞入一套完整的、带范例的测试规范，情况就完全不一样了，它对“该按什么风格写”这件事就突然非常有把握了。

所以skills做的事情，本质上是把“本来只存在于你项目文档里、团队老同事脑瓜里”的隐性知识，变成模型能在关键时刻读到的显性上下文。它不是玄学，也不是什么黑魔法，就是在正确的时间点往上下文里塞正确的信息。这个过程谁都能做，但做成结构化、标准化，能让AI在需要时自动读取而不是每次手动粘贴，这就是skills文件夹存在的意义了。

1.3 “记忆”到底放在模型权重里，还是放在文件系统里

再往深一层想，AI编程助手的工作流是有固定套路的。你给它一个任务，它在内部会经历“理解需求、规划步骤、读取文件、生成代码”这样一个循环。这个时候如果你在项目根目录放一个“技能包目录”，并且让助手在任务开始前先扫描这个目录，它就会知道自己有哪些“专属招式”可用，然后主动去读取匹配的SKILL.md。

这就相当于给了AI一个外挂记忆库。

模型的权重在训练完的时候就已经固定了，它脑子里装的是全世界各类项目的平均水平。而你的项目是特殊的，你需要的不是“普遍正确”的代码生成，而是“在你项目语境下正确”的代码生成。skills这个机制，相当于把一个无限可扩展的“记忆层”架在了模型外面。这个思路妙就妙在：它没有碰模型本身，也不需要微调，纯靠文件系统里的结构化内容就实现了“个性化”。我第一次想通这个道理的时候，感觉挺受震动的，因为这意味着个人积木式的知识资产第一次能直接对接AI了。

2. skills技能包的目录结构、文档规范与设计原则

2.1 一个标准技能包的目录长什么样

刚开始接触skills的时候，我以为是某种复杂框架，翻了不少资料才发现核心就是一个文件夹加一个Markdown文件。以我目前项目里在用的一个技能包为例，它的目录结构长这样：

.skills/ ├── component-testing/ │ ├── SKILL.md │ └── examples/ │ ├── button.test.tsx │ └── modal.test.tsx ├── project-cleanup/ │ └── SKILL.md └── readme.md

解释一下这个结构的逻辑。.skills目录放在项目根目录，扫描器会自动识别。里面每个子文件夹就是一个独立技能包，子文件夹的名称就是技能ID。每个技能包里面必须要有一个SKILL.md文件，这是技能的核心说明文档。如果技能涉及代码范例，我会在旁边放一个examples/文件夹，里面存具体可参考的代码文件。最开始我以为把例子全部写在SKILL.md里就行，后面发现容易写得冗长，一次性塞进上下文负担也大，干脆拆成文件让AI按需读取，更清爽。

这个目录结构，本质上是在模仿人类写“领域知识手册”的方式：先有概述，再有细节，最后有案例。不同之处在于，这份手册的读者不是人，是AI。

2.2 SKILL.md里的Frontmatter，前三个字段决定了技能什么时候会被触发

SKILL.md本身是带YAML头部（Frontmatter）的Markdown文件，对AI来说最重要的就是头部那段元信息。我实际用下来，三个字段最关键：

--- name: component-testing description: 项目组件单元测试编写规范。当用户要求为组件编写测试、补充测试用例、修复失败的单测时使用。 allowed-tools: write, edit, read ---

name字段是技能ID，一般跟文件夹同名，扫描器靠这个来索引。description字段是重中之重，它决定了AI在什么时候会想到用这个技能。我之前犯过一个错误，把description写得很泛，比如“组件测试相关”，结果AI识别精度很低。后来我学到的经验是：description必须包含具体的触发场景，写得越具体越好，最好把动词场景都列出来，比如“补测试”、“修单测失败”、“为组件增加用例”，这样AI在任务语义匹配时才能精准命中。allowed-tools字段用来声明这个技能在执行过程中允许调用哪些工具。限制这个是有讲究的，防止技能在不该动手的时候乱改文件。

2.3 正文体例要“目标-步骤-范例-禁区”四位一体

Frontmatter下面就是正文，这部分我总结了一套比较稳的四段式体例。

第一段写明白“这个技能的目标是什么”，让AI知道什么时候算完成了。第二段给完整操作步骤，可以是一二三四五的顺序步骤，也可以是一个带分支的流程。第三段必须给正反两个范例，正向范例告诉AI“就该这么写”，反向范例说明“这么写是错的，错在哪”。第四段是禁区，也就是“无论什么情况下都不要做X”。这第四段非常有用，能把模型经常性犯的错误提前堵住。举个例子，我在测试技能里写了“禁止使用screen.debug()输出调试信息到最终提交”，AI就再也没往提交的测试代码里加过这行。

这套体例的实质是在给AI建模一个“决策空间”。目标定义了终态，步骤规定了路径，范例提供了锚点，禁区划定了边界。四者合在一起，一个模糊的“帮我写测试”请求，才能在AI那边被拆解成一个可执行的确定性方案。

3. 手把手搭一个实用的组件测试技能包

3.1 先从明确“技能边界”开始

写技能之前我建议你先想清楚一件事：这个技能包要覆盖什么、不覆盖什么。很多人一上来就写个大而全的技能，结果啥都管，啥都管不细，AI读了反而不知道该按哪条执行。我的习惯是：一个技能只解决一类问题，控制在几百行以内。

以组件测试为例，我会明确这个技能只处理“组件级单测”这一类问题，不涉及端到端测试，也不涉及工具函数测试。边界一收窄，技术要点就变得清晰：渲染方式统一用真实挂载，事件触发统一走userEvent，异步断言统一用waitFor，交互覆盖hover、click、change等关键场景。

3.2 按四段式结构写SKILL.md的真正内容

直接贴一份我实际在用的精简版内容，可以作为起始模板：

--- name: component-testing description: 项目组件单元测试编写规范。当用户要求为组件编写测试、补充测试用例、修复失败的单测、调整测试结构时使用。适用于所有src/components目录下的React组件。 allowed-tools: read, write, edit, grep --- # 组件单元测试编写规范 ## 目标 产出符合项目规范、稳定可靠、可读性强的组件单元测试。 ## 操作步骤 1. 定位组件源码，梳理组件的Props、事件与对外暴露的能力。 2. 列出需要覆盖的测试场景（渲染、交互、异步更新、边界条件）。 3. 按照“挂载-断言-交互-再断言”的方式组织用例。 4. 运行测试命令确认全部用例通过：npm run test -- --watch=false。 5. 自查：无调试残留、无无效断言、覆盖关键交互路径。 ## 规范细则 - 渲染：统一用 @testing-library/react 的 render。 - 断言：统一使用 jest-dom 扩展匹配器。 - 交互：统一使用 userEvent，禁止使用 fireEvent。 - 异步：等待元素出现/消失使用 waitFor，不得使用固定sleep。 - 结构：describe 描述组件名，it 描述行为，必要时嵌套 describe。 ## 正面范例 ...（这里贴一份实际可用的组件测试代码）

写完正文后，我还会把一份完整的真实测试案例放在examples/button.test.tsx里，并在正文中用一两句话指向它。AI在操作时如果觉得不够具体，就会去读取这个范例文件。

3.3 把技能安装进项目并验证效果

SKILL.md写完之后，把它放进.skills/component-testing/SKILL.md，然后在项目根目录放一个简单的说明文件，比如.skills/readme.md，告诉助手“开始任务前先扫描本项目技能包目录”，然后就可以实测了。

验证效果的建议方式是准备几个典型测试任务：给一个已有组件补测试、修复一个故意写错的测试、给一个新组件从零开始写测试。连续试几个任务，观察AI的输出是否稳定贴合规范。我第一版测试效果其实不理想，连续三个任务里有两个还是会跑偏。别灰心，这很正常，此时需要回到SKILL.md找原因，大概率是描述不够精确或者范例不够典型。

我后来经过三轮迭代，把期望效果从“能跑”提升到“跑得稳”之后，输出质量才真正稳定下来。这个过程中最耗时间的是打磨范例，而不是写规范。因为AI对规范的理解是抽象的，但案例是具体的，正例给得好，AI模仿出来的代码风格自然就正。

4. 常见问题与排查技巧：为什么我配了skills没效果

4.1 技能总不被调用，问题多半出在description

我在实际使用中遇到的最典型问题，就是明明配置好了component-testing技能包，但让AI“给Modal组件补测试”时，它完全没提这个技能，自己埋头就是一顿硬写。一开始我以为是指令长度的问题，后来排查才发现，根因出在description字段太宽泛。

AI侧的语义匹配机制，是靠对比“用户当前任务的语义”和“技能包description的语义”来判断是否触发。如果description写的是“组件测试相关”，那在AI看来任何带“测试”二字的任务都可能匹配上，匹配范围太广反而导致精确度下降；如果写成“当用户要求为src/components目录下的组件编写测试、补充用例、修复单测失败时使用”，这种带具体对象、具体动作、具体路径的描述，会让匹配精准很多。

4.2 技能读取了却像个摆设，要检查规范是否够“可执行”

还有一种情况比较头疼：AI确实读了SKILL.md，但生成的代码还是我行我素。这时候我一般会检查规范里面是否全部、系统、具备可执行性。比如“交互建议使用userEvent”这个表述就不行。“建议”这个词在AI那儿约束力很弱，它可以选择听，也可以选择不听。把它改成“交互统一使用userEvent，禁止使用fireEvent”，明确给出指定工具和禁用工具的约束，AI的执行力瞬间就上来了。

4.3 多个技能包打架，命名和目录规划有讲究

随着技能包多了之后，可能出现另一个问题：多个技能的description指向了同一类任务，AI不知道选哪个，干脆随便选一个执行。避免这个问题，我在命名和目录规划上遵从三条原则：技能名避免使用过于通用的词汇，比如“testing”在清单里就会出现歧义，建议叫“react-component-testing”；description里明确写清楚适用领域和不适用的边界；不把两个职责重叠的技能包放同一个目录层级。

做一个总结性速查表给大家：

4.4 经验之谈：好技能是养出来的，不是写出来的

最后说点心得体会。skills这东西，不要指望一次写完就一劳永逸。我前前后后迭代了大概两三周，技能包才从“勉强能看”变成“真的好用”。头几次跑出来的结果不尽如人意是很正常的，重要的是建立一个反馈闭环：每次遇到AI输出不如意的场景，回头审视SKILL.md，看看是哪里没写透；每次在人工review时发现重复性修改，就把它沉淀成新的规范或新的禁区条目。

我现在的工作流里，skills已经变成和代码库一样需要持续维护的东西。功能代码更新了，技能包里的范例也需要同步更新；团队规范变了，技能包里的禁区条款也要跟着调整。从效果上看，用了这套机制之后，我处理组件测试这件事的效率至少提升了50%，关键是AI生成代码的风格稳定性提升了很多，review的过程从“逐行修改”变成了“偶尔微调”。这种把个人知识和团队规范沉淀成结构化资产、并且直接对接AI工作流的方式，是效率工具类型里少见的高杠杆技术，值得花时间认真投入。