Skill框架：给AI编程助手的上下文契约与实践指南

如果你用 AI 编程助手写过超过三个月代码，大概率遇到过这种场面：同一个项目，昨天让它写的工具函数和今天让它补的模块，风格对不上；明明是同一个数据库表，每次一问它都得把字段解释一遍；更难受的是，交给它做代码评审，它一会儿揪着格式化不放，一会儿又把真正的并发隐患放过去。

这些问题不是 AI 笨，而是缺少一个“上下文契约”。Skill 框架，正是为这件事设计的——它相当于给 AI 编程助手配了一套可复用的“岗位说明书”，把你所在项目的规范、经验、最佳实践预先封装成文件，让 AI 在动手前按需读取，而不是每次靠你临场口述。

这篇文章，我想从一个在多个项目里把 Skill 框架真正用起来的开发者角度，聊聊它到底是什么、怎么设计、怎么搭建、怎么调试，以及我踩过的几个坑。适合觉得 AI 代码助手“不够懂你”、又不想每次都从头讲背景的开发者。

1. Skill 框架到底是什么：先治“AI 失忆症”

1.1 普通对话式编程的问题

用过一个月的 AI 编程助手，再回到纯手写代码的人很少了，但一直用下去的人大多会有同一个感受：它“每次见面都像第一天认识你”。这个问题的根源很直白——大模型本身没有跨会话记忆，你每次新建对话，它看到的只是一个光秃秃的请求，至于你们昨天约定过的命名规范、项目里锁定的技术版本、上个月定下的异常处理策略，它全都不知道。

你可能会说，那就把规则写进系统提示词。确实可以，但系统提示词有长度限制，而且写得越多，AI 真正执行任务时的“注意力”就越容易被稀释。早期我用过一个很长的提示词，把团队规范全部拼进去，结果它每条规则都记得，但每条都执行得不彻底——审代码时既纠结缩进，又纠结变量命名，真正的业务逻辑漏洞反而被挤到后面。

换一个角度想，这其实不是 AI 的智力问题，而是信息组织问题。就像你招了一个能力很强的新人，但不给他看部门制度、不给他看技术规范，直接让他上手写代码，他当然只能凭常识干活。Skill 框架解决的就是这件事：把“常识之外的项目专属知识”系统性地交给 AI。

1.2 Skill 是“技能包”而不是“提示词”

Skill 框架解决问题的方式，是改变信息的投喂方式。它不再把规则塞进一句提示词里，而是把能力打包成一个“文件夹”：里面有说明书、参考资料、示例、检查清单。AI 在需要时，可以主动、按需地翻阅这些文件。这里的关键区别是“按需”两个字：不是把所有内容一次性灌进去，而是像人查手册一样，先读总纲，再根据任务需要查具体的章节。

这样带来的直接好处有三个。第一，上下文更干净，AI 能集中精力处理眼前的任务，而不是被一堆背景规则干扰。第二，知识可以沉淀，项目里的决策、规范、踩坑记录都放在 Skill 里，换人换机器都不丢。第三，能力可以复用，同样一套 Skill，今天用来审 A 项目，明天换成 B 项目，只要改里面的参考资料就行。

很多刚接触的人会问我：这不就是一套高级提示词吗？是，也不是。提示词是“一次性说话”，Skill 是“持续在场的能力”。提示词写在对话框里，会话结束就没了；Skill 是磁盘上的文件，每次会话都能被找到。把它理解成“给 AI 配的岗位 SOP”会更准确——新人可以翻着 SOP 干活，但 SOP 本身不是那句“欢迎入职”的问候。

1.3 一个 Skill 的典型组成

在我见过的各种实现里，一个合格的 Skill 通常包含这么几块内容：

• 主说明文件：描述这个 Skill 是什么、什么时候用、怎么用，是整个技能包的入口，类似一本书的目录和序言。
• 参考资料目录：存放领域知识、技术规范、项目约定，AI 需要细节时会来这里查。
• 示例与模板：给 AI 一个“输出长什么样”的参照，比如审查报告模板、工具函数写法示例。
• 规则与约束：明确告诉 AI 哪些能做、哪些不能做，这是减少胡来行为的关键。

这套结构不复杂，但正因为简单，很多人会低估它。实际用下来我发现，文件怎么放、说明怎么措辞、参考资料怎么排版，都直接影响 AI 的理解质量。后面我会逐个拆开讲。

2. 设计 Skill 前要琢磨清楚的几件事

2.1 先定边界：不是所有事都值得做成 Skill

我在最开始犯的错误，就是想给所有东西都做 Skill。做过代码审查的、做数据库迁移的、做性能优化的，连回复邮件都想做一个。结果 Skill 文件越来越多，真正用得上的没几个，维护还累。后来我给自己定了一条判断标准：一个任务如果满足以下条件，才值得做成 Skill——高频（每周都要用）、有明确规范（能写出确定性步骤）、需要背景知识（不写 AI 就不知道）、输出有固定格式（否则每次都不一样）。

反过来，探索性、一次性的任务，比如“帮我想个新功能的交互方案”“把这个算法讲给我听”，就不适合封装。这类任务的价值恰恰在于 AI 的自由发挥，你把它框死了反而浪费。这就像工具箱里的螺丝刀和瑞士军刀，螺丝刀专门拧螺丝，瑞士军刀什么都干一点，但都不精。Skill 的目标是做一把好用的螺丝刀，不是做一把万能的军刀。

2.2 信息组织：AI 是“按需读取”的

这是 Skill 设计里最容易被忽略、但对效果影响最大的一点。你要把 Skill 当成一本参考书来写，而不是一张海报。参考书的特点是：读者先看目录，再翻到需要的章节；海报的特点是：所有内容必须在一屏内看到。

AI 读取 Skill 也是类似逻辑。主说明文件相当于目录和总纲，要写得精炼、结构清晰，告诉 AI“这个技能干什么、入口在哪”。参考资料则要分层：通用的放一层，项目专属的放另一层，临时性的再放一层。这样 AI 遇到不同类型的问题，只会加载对应层级的文件，不会把所有内容都拽进上下文。

打个比方，一个“数据库迁移”Skill 的主文件，只需要说明“何时触发、分几步走、风险等级怎么判断”；至于具体某张表的字段变更记录，应该放在项目专属的参考资料里，让 AI 真遇到那张表时才去查。你要是把全公司几十张表的说明全写进主文件，AI 光看完就已经超载了。

2.3 语言、触发词和场景匹配

不少中文开发者习惯把所有内容都写成中文，这本身没问题，但要注意一点：AI 在读取时对关键词的匹配是字面优先的。如果你的 Skill 主文件里只写了中文名，而会话里用户用的是英文缩写，AI 可能找不到入口。我的做法是：主文件里写清楚“中英文别名”和“触发场景”，比如同时声明“代码审查 / code review / review”，并在说明里强调哪些场景必须激活这个 Skill。

触发词不是越花哨越好。用最短、最自然的词，反而能让 AI 正确识别。我见过有人给代码审查 Skill 起名叫“终极全方位无死角代码体检”，结果 AI 每次看到“review”都不确定该不该触发，白白浪费了这个技能。名字越直白，识别越准。

3. 搭建 Skill 的标准步骤：目录、文件、内容

3.1 从零建目录

一个规范的 Skill 目录结构，我放下面。命名全小写、用连字符分隔，参考知识文件按主题拆。注意 references 目录不要嵌套太深，AI 遍历文件时，层次越浅越容易找。

code-review-skill/ ├── SKILL.md ├── references/ │ ├── coding-style.md │ ├── performance-checklist.md │ └── security-notes.md ├── examples/ │ └── review-report-template.md └── assets/ └── icons/

我自己的习惯是：主文件固定叫 SKILL.md，这样任何 AI 编程助手都能靠约定找到它。references 目录放知识，examples 目录放模板，assets 放图片等资源。目录不要太深，最好不超过三层。之前我试过在 references 下再建“前端/组件/表单验证/”这种深层目录，AI 经常漏读，后来扁平化之后明显好多了。

3.2 写透说明文件的六个要素

主说明文件是整个 Skill 的灵魂，写得好不好，直接决定 AI 能不能正确使用它。我归纳了六个必写要素，缺一个就容易翻车。

第一，身份定义。用一两句话说清楚这个技能是干什么的。比如“本技能用于对前端组件代码进行结构化审查，发现可维护性、性能与安全隐患”。身份定义要具体，不要写“帮助开发者提高代码质量”，这种话等于没说。

第二，使用时机。明确列出什么时候该激活这个技能。比如“当用户要求审查代码、执行 code review、或提到性能问题时使用”。写好使用时机，AI 才能判断该不该调出这个技能。

第三，工作流程。这是核心中的核心。把任务拆成明确的步骤，写清楚每一步做什么、产出什么。比如代码审查可以拆成：先读取项目结构，再定位变更文件，再逐文件检查，最后汇总成报告。AI 的执行力和工作流的清晰程度强相关，你把步骤写得越细，它跑起来就越稳。

第四，输出规范。告诉 AI 最终交付物长什么样。需要给一个明确的模板，比如“审查报告必须包含：问题位置、严重级别、问题原因、修改建议”。有模板，输出才稳定。

第五，边界与禁忌。这个最容易被忽略，也最重要。要写明哪些事情绝对不能做。比如“不修改用户源码”“不评价代码风格之外的无关问题”“不编造不存在的性能问题”。边界清晰，AI 才不会跑偏。

第六，参考索引。列出这个 Skill 配套了哪些参考文件、分别在什么情况下查阅。相当于给 AI 一张地图：“你要查性能规则，去看 performance-checklist.md；要查安全规则，去看 security-notes.md”。

3.3 知识文件怎么写才不浪费

很多人写知识文件，喜欢把项目文档整个复制进去，这是最大的浪费。AI 真正需要的是两类知识：决策型知识和约束型知识。决策型知识，是过去项目里讨论过、拍板过的取舍，比如“为什么这里选 Redis 而不是用本地缓存”。约束型知识，是绝对不能做的事，比如“禁止在事务内发起远程调用”。

这些知识要写得像“会议纪要”而不是“说明书”。说明书讲功能，会议纪要讲理由。AI 掌握了理由，做类似的判断时才能举一反三。比如你在知识文件里写“缓存失效时间必须小于 5 分钟”，AI 只会机械遵循；如果你补一句“因为支付流程中最长回滚窗口是 5 分钟”，AI 以后遇到类似的资金操作，就会主动考虑时间窗口问题。

知识文件还需要注意一个排版上的细节：用小标题、短段落、列表来组织，别写成长篇大论。AI 读取 markdown 文件时，结构越清晰，定位信息越快。我也建议每个主题控制在五十行以内，超过就拆分。

4. 实操落地：一个“前端组件代码审查”Skill 的完整过程

4.1 场景定义与规则编写

理论讲完，拿一个具体例子走一遍。假设我在维护一个中后台前端项目，最常见的需求是让 AI 帮我做代码审查。但我发现，不写 Skill 时，AI 的审查视角很乱：有时候纠结变量命名，有时候忽略接口鉴权，输出格式每次也都不一样。所以我决定给它的审查能力做个 Skill。

第一步，我先写下身份定义和使用时机。身份定为“前端组件代码审查助手”，使用时机是“用户提及 review、审查代码、检查组件质量、或者提交前自查”。第二步是定审查维度，我参考团队多年的 Code Review 经验，归结为四个维度：可维护性、性能、安全性、可访问性。每个维度都写了明确的检查点，比如安全性要看是否校验接口返回数据、是否把敏感信息打印到日志；性能要看是否有无效重渲染、是否有大数据量循环体内计算。

这些检查点不是我想当然写的，而是从过去几个月的真实 bug 记录里反推出来的。建议你也这样做——先复盘自己团队踩过的坑，再把规则写进 Skill，而不是凭空想象。手头没有现成素材的，可以把主流代码规范里的检查项先摘进来，后续再迭代。

4.2 工作流编排：让 AI 按“先全局后局部”审查

有了规则，接下来是编排工作流。我给这个 Skill 设计的流程分五步，每个步骤都明确了 AI 该做什么。第一步，先读取项目目录结构，理解项目类型和技术栈，不做任何判断。第二步，定位用户希望审查的目标文件或变更文件列表。第三步，先做整体架构层面的审视，比如组件拆分是否合理、状态管理是否集中。第四步，才进入逐文件细节审查，按照四个维度逐条过。第五步，把问题汇总成报告。

这一步最关键的设计是“先全局后局部”。一开始我把步骤设计反了，让 AI 直接从头到尾审查每个文件，结果它被局部细节牵着走，失去全局视角。后来改成先看结构、再看细节，效果明显提升。这说明 Skill 里的工作流程，本质上是你把“自己会怎么干活”的思维过程透明化。

下面是我在主文件里写的简化版流程，供参考。注意流程步骤之间要有明确的产出物，比如“读取完成之后必须输出技术栈摘要”“审查完成之后必须输出问题清单”，这样 AI 每一步都有抓手。

## 工作流程 1. 读取项目目录结构，输出技术栈摘要（框架、UI库、状态管理方案）。 2. 根据用户指出的目标，列出待审查文件清单；如果未指定，则默认审查最近修改的 5 个文件。 3. 整体架构审视：组件是否过度拆分或过于庞大；状态管理是否符合项目既有模式。 4. 逐文件按四个维度审查：可维护性、性能、安全性、可访问性。 5. 汇总输出审查报告，按严重级别排序。

4.3 运行验证与迭代调优

Skill 写完不是终点，第一次运行大概率不能让你满意。我记得头一次用它做审查，AI 报告里列了十几个问题，但有一半是重复的，还有两个“问题”其实是业务有意为之。原因是我在“边界与禁忌”里没写清楚“已知业务例外”。我把这条补进知识文件：遇到与业务强相关的写法，不确定时先标注“需要人工确认”，不要直接判定为缺陷。

第二次运行，重复问题少了很多，但 AI 对安全性的检查还是偏弱。我对比后发现，问题出在知识文件里安全规则写得太宽泛——“检查数据校验”这种描述对 AI 来说太抽象。我改成具体清单：接口响应是否做类型断言、错误信息是否会暴露内部实现细节、日志是否记录 token 或密码字段。改成清单之后，AI 的检查立刻有了抓手，命中率明显提高。

这里分享一个迭代技巧：每次跑完 Skill，把结果里“AI 漏掉的问题”记下来，去补充对应维度的检查点；把“AI 误报的问题”记下来，去补充边界与禁忌。这样迭代三四轮，Skill 就会越来越贴合你的项目。这个过程有点像在训练一只导盲犬，不是它天生就会，是你不停地告诉它哪条路能走、哪条路有坑。

4.4 运行调试中的小工具思路

在实际调试 Skill 时，我习惯在 references 下放一个 self-test.md，里面写几个典型 Bug 样例。每次改动 Skill，就让 AI 用这些样例自测一遍，看能不能找出预设问题。这一招非常好用，相当于给 Skill 写了单元测试。你自己也可以往里面放“故意写错的代码片段”，比如一个循环体里发同步请求的死循环写法，或者一个没做空值校验的解构赋值。定期跑一遍，你就能知道 Skill 有没有退步。

5. 常见问题与排查技巧实录

5.1 问题速查表

用 Skill 的过程中，我总结了一张问题速查表。如果你遇到类似状况，可以直接按表排查。

5.2 我踩过的几个坑

第一个坑，是过度设计。我做过一个超大的 Skill，主文件写了将近三百行，涵盖架构设计、编码规范、测试策略、部署流程，结果 AI 每次激活它都像背了一本书，执行起来反而迟缓，还经常自相矛盾。后来我把它拆成三个独立 Skill，每个只管一件事，效果立刻好了。所以我的建议是：一个 Skill 只解决一类任务，宁可多拆几个，也别堆成巨人。

第二个坑，是 Skill 之间相互冲突。我同时启用了“代码规范”和“快速原型”两个 Skill，结果 AI 在写原型代码时也套用严格的规范流程，导致原型迟迟出不来。解决办法是给每个 Skill 写明“使用场景”和“互斥条件”。比如快速原型的使用时机里明确写“仅限探索性验证，不适用于需要提交的生产代码”。

第三个坑，是说明文件里出现大量的形容词。比如“高质量”“优雅”“健壮”，AI 听到这些词会很迷茫，因为它不知道怎么量化。正确的写法是给形容词配指标：高性能 = 首屏渲染时间小于 2 秒；可维护 = 单文件不超过 200 行，函数不超过 30 行。指标远比形容词可靠。

5.3 把 Skill 变成团队资产

当你把一个 Skill 调教到好用之后，下一步是让它离开你的个人电脑。我的做法是在团队仓库里建一个 skills 目录，用独立分支维护。命名上统一约定：动词开头，比如 frontend-review、db-migration、log-debugging。每次新增或修改 Skill 都要过一轮评审，至少要有人扮演“AI 使用者”实际跑一遍，验证流程是否顺畅。

这里还有个组织技巧：把 Skill 里“通用规则”和“项目专属规则”物理分离。通用规则文件放共享仓库，每个开发者克隆一份；项目专属规则放各自项目里，通过声明方式引用。这样做的好处是，团队规范更新时，只需要改通用规则文件；项目差异不进通用文件，避免规则越来越臃肿。

我自己在多个项目里的体会是，Skill 框架真正教会我的不只是如何调教 AI，更是如何把团队里的隐性知识显性化。很多代码审查要点、架构决策理由、踩坑经验，过去都只存在老员工的脑子里，现在可以结构化沉淀下来，让 AI 继承一部分“团队记忆”。我见过团队里有人离职后，新人也能力很快上手项目，原因就是 Skill 把大量项目上下文固化住了。

最后再分享一个小技巧：Skill 不要一上来就做全套，先从一个你每周都会做的、最烦最重复的场景开始。把它封装好、跑顺、迭代到让你舒服，你就自然理解这套框架的边界和力量了。等你积累了足够的经验，再回头把其他场景逐个做成 Skill，效率会远超想象。