企业官网建设流程全解析

1. 从“superpowers”说起：这套方法论到底在解决什么问题

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手，大概率已经在各种社区里刷到过它。简单说，superpowers 是一套面向 AI 编程代理的“技能框架”与开发方法论，它要解决的核心问题只有一个：让 AI 代理在真实项目里干活时，不再东一榔头西一棒子，而是像一支训练有素的小队那样，有章法、有记忆、有分工地推进任务。

我自己是从去年开始重度使用 Claude Code 做日常开发的，最开始的状态和大多数人一样——打开终端，敲一句需求，等它吐代码，然后复制粘贴、手动验证、发现问题再追问。这种用法在写个脚本、改个小 bug 的时候还行，一旦项目稍微复杂一点，比如要重构一个模块、要跨多个文件改接口、要保证改动不破坏已有测试，AI 代理就开始“失忆”了：它不记得十分钟前自己改过什么，不记得项目的代码规范，甚至会把之前已经修好的问题又改回去。这不是模型能力不够，而是缺少一套约束它行为的框架。

superpowers 这类 agentic skills framework 的价值就在这里。它把“一个合格的开发者应该怎么做事”拆解成一个个可复用的技能单元，比如“先读代码再动手”“改动前先跑测试”“提交前做自检”“遇到不确定的地方先问而不是猜”。这些技能不是硬编码在模型里的，而是以配置文件、提示词模板、工作流脚本的形式存在，AI 代理在执行任务时会按需加载。你可以把它理解成给 AI 代理装了一套“职业素养操作系统”——它本来就会写代码，现在它知道该怎么在团队里写代码。

这套东西适合谁？我的判断是三类人。第一类是已经在用 Claude Code 或 Codex CLI，但觉得“它好像没那么聪明”的开发者，问题往往不在模型，而在你给它的工作环境太简陋。第二类是想把 AI 代理引入团队协作的技术负责人，你需要一套可复制、可审计的规范，而不是每个人凭感觉和 AI 对话。第三类是对 agentic 开发方法论本身感兴趣的人，superpowers 的设计思路——技能解耦、上下文管理、渐进式披露——对理解整个 AI 代理生态都很有帮助。接下来我会从设计思路、核心机制、实操落地、问题排查几个层面，把这套东西拆开讲清楚。

2. 核心设计思路拆解：为什么是“技能框架”而不是“提示词合集”

2.1 从“一次性对话”到“可积累的能力”

大多数人用 AI 编程助手的方式是“一次性对话”：有问题就问，问完就关，下次重新开始。这种模式的问题在于，所有上下文都压在单次会话的窗口里，一旦超出窗口限制或者会话中断，之前积累的理解就全丢了。superpowers 的第一个设计选择，就是把能力从“对话”里抽出来，变成独立的、可持久化的技能文件。

具体来说，一个技能通常包含几个部分：触发条件（什么情况下该用这个技能）、执行步骤（具体怎么做）、检查清单（做完之后怎么验证）、以及常见陷阱（哪些地方容易出错）。这些内容以 Markdown 或 YAML 的形式存放在项目目录里，AI 代理在启动时会扫描这些文件，根据当前任务类型决定加载哪些技能。这个设计和 Claude Code 本身的CLAUDE.md机制是一脉相承的，但 superpowers 把它做得更结构化、更细粒度。

我举个实际例子。在没有技能框架的时候，你让 AI 改一个函数，它可能直接就把代码改了，不跑测试，不检查调用方。有了技能框架之后，你可以定义一个叫“安全重构”的技能，触发条件是“当任务涉及修改已有函数签名时”，执行步骤包括：先搜索所有调用点、列出受影响的文件、生成改动计划、逐个修改、每改一个跑一次相关测试、最后汇总报告。AI 代理在识别到你的需求属于“重构”类任务时，会自动加载这个技能，然后按步骤执行。这就是从“它会写代码”到“它会按正确流程写代码”的转变。

2.2 渐进式披露：为什么不能一次性把所有规则塞给 AI

这里有一个很多人会踩的坑：既然技能框架这么好，那我是不是应该把所有规则、所有规范、所有注意事项都写进配置文件里，让 AI 一次性全部加载？答案是绝对不行。原因有两个，一个是技术上的，一个是认知上的。

技术上的原因很直接：上下文窗口是有限资源。你把几千行规则塞进去，模型真正用于理解你当前代码的注意力就被稀释了。实测下来，当系统提示词超过一定长度后，模型对其中具体条目的遵循程度会明显下降，尤其是那些排在中间位置的规则，很容易被“遗忘”。这不是模型厂商的锅，而是当前所有大语言模型的通病。

认知上的原因更微妙。AI 代理在执行任务时，它的“工作记忆”和人类似，同时处理的信息量是有限的。如果你一次性给它二十条规则，它在做每一个决策时都要在脑子里过一遍这二十条，结果就是决策变慢、容易顾此失彼。superpowers 采用的策略叫渐进式披露：核心规则只有几条，永远加载；具体技能按需加载，用到哪个加载哪个；详细参考文档只在需要深入时加载。这个分层设计和人类专家的工作方式是一样的——一个资深工程师不会在每次写代码时都把设计模式手册从头翻一遍，他只在遇到特定问题时才去查相应章节。

2.3 技能之间的组合与依赖关系

单个技能能解决的问题有限，真正体现框架价值的是技能之间的组合。superpowers 里有一个很聪明的设计：技能可以声明自己依赖哪些其他技能，也可以声明自己在什么条件下会触发其他技能。这就形成了一个有向图，AI 代理在执行任务时，实际上是沿着这个图在走。

比如“新功能开发”这个技能，它可能依赖“需求澄清”“代码搜索”“测试先行”“增量提交”这几个子技能。当 AI 代理加载“新功能开发”时，它会自动把依赖的子技能也加载进来，形成一个完整的工作流。而“代码搜索”这个技能又可能被“重构”“修 bug”“代码审查”等多个上层技能复用。这种设计的好处是，你不需要为每个场景都写一套完整流程，只需要把原子技能定义好，然后在上层做组合。

我在实际项目里验证过这个机制的效果。我们有一个中等规模的 TypeScript 项目，大概两百多个文件。在没有技能框架的时候，让 AI 做一次跨文件重构，成功率大概只有六成左右，经常出现改了一半、调用方没更新、测试挂掉的情况。引入技能框架之后，我把“重构”拆成了“影响面分析”“接口冻结”“逐个替换”“回归验证”四个技能，让 AI 按顺序执行。成功率提升到了九成以上，而且每次改动的报告都很清晰，review 起来省了很多时间。

3. 核心机制与实操要点：技能文件到底怎么写

3.1 技能文件的基本结构

一个标准的技能文件通常包含以下几个字段，我用一个实际用过的“测试先行”技能来举例说明：

name: test-first description: 在修改任何业务逻辑之前，先编写或更新对应的测试用例 trigger: - 任务类型为功能开发或 bug 修复 - 目标文件包含业务逻辑代码 - 项目存在测试框架配置 steps: - 定位目标函数或模块对应的测试文件 - 阅读现有测试，理解当前覆盖范围 - 根据需求编写新的测试用例，确保测试能够失败 - 运行测试，确认失败原因符合预期 - 再开始修改业务代码 - 修改完成后重新运行测试，确认通过 checklist: - 新测试是否覆盖了需求中的所有边界条件 - 测试失败信息是否清晰指向未实现的功能 - 是否有测试因为环境问题而误报 pitfalls: - 不要为了让测试通过而修改测试断言 - 如果项目没有测试框架，先和用户确认是否引入

这个结构看起来简单，但每个字段都有讲究。trigger决定了技能什么时候被激活，写得太宽会导致技能被滥用，写得太窄又会在需要时加载不上。我的经验是，trigger 条件最好控制在两到三条，并且尽量用“任务类型”“目标文件特征”“项目配置”这类可客观判断的条件，避免用“当用户看起来需要时”这种模糊描述。

steps是技能的核心，它定义了 AI 代理的执行顺序。这里有一个关键原则：每一步都应该是可验证的。什么叫可验证？就是做完这一步之后，你能明确判断它是成功了还是失败了。比如“阅读现有测试”这一步，验证方式就是 AI 能说出当前测试覆盖了哪些场景。“运行测试确认失败”这一步，验证方式就是终端输出里有明确的失败信息。如果某一步没法验证，那它就不应该出现在 steps 里，而应该放到 checklist 或者 pitfalls 里作为提醒。

3.2 触发条件的写法与常见误区

触发条件是技能框架里最容易写错的部分。我见过太多人把 trigger 写成了一段自然语言描述，比如“当用户要求进行代码重构时”。这种写法的问题在于，AI 代理需要先理解“什么算重构”，而不同人对重构的定义是不一样的。有人觉得改个变量名算重构，有人觉得只有大规模结构调整才算。这种模糊性会导致技能要么被过度触发，要么该触发的时候没触发。

更好的做法是用可观测的信号来定义触发条件。比如：

• 任务描述中包含“重构”“重命名”“提取”“内联”等关键词
• 目标文件的行数超过某个阈值
• 目标函数被超过 N 个其他文件引用
• 项目中存在tsconfig.json或pyproject.toml等配置文件

这些条件都是 AI 代理可以直接从环境和输入中判断的，不需要额外的语义理解。当然，关键词匹配也不是万能的，有时候用户会用“整理一下这段代码”这种说法来表达重构需求。这时候可以配合一个兜底策略：如果任务涉及修改已有代码且改动范围超过一定行数，就默认加载重构相关技能，同时在执行前向用户确认。

还有一个常见误区是 trigger 条件之间的逻辑关系没写清楚。是“满足任意一条就触发”还是“必须全部满足才触发”？这个必须在文件里明确声明。我的建议是默认用“任意一条”，因为技能加载多了顶多是多做一些检查，加载少了可能导致流程缺失。但如果你有性能或成本上的考虑，也可以用“全部满足”，只是要接受偶尔漏加载的风险。

3.3 步骤设计的粒度控制

steps 的粒度是另一个需要仔细权衡的地方。粒度太粗，比如只写“修改代码”，那和没有技能框架没区别；粒度太细，比如把“打开文件”“定位到第 42 行”“输入字符”都写进去，那 AI 代理就变成了一个只会执行固定脚本的机器人，失去了灵活性。

我的经验法则是：每一步对应一个可以独立验证的中间产物。比如“生成改动计划”这一步，产物是一份列出所有待修改文件和修改内容的清单。“修改第一个文件”这一步，产物是文件内容的变化。“运行相关测试”这一步，产物是测试结果。这样划分下来，一个中等复杂度的技能大概有六到十步，既不会太粗导致失控，也不会太细导致僵化。

另外，steps 里应该明确标注哪些步骤是必须执行的，哪些是条件执行的。比如“运行测试”在大多数情况下是必须的，但如果项目根本没有测试框架，这一步就应该跳过并记录原因。这种条件逻辑可以用简单的 if-then 语法写在步骤描述里，AI 代理在加载技能时会解析这些条件。

3.4 检查清单与陷阱记录的价值

checklist 和 pitfalls 这两个字段经常被忽视，但它们是技能框架里最有“经验价值”的部分。checklist 是执行完技能后的自检清单，它回答的是“我怎么知道我做对了”。pitfalls 是已知的坑，它回答的是“哪些地方容易出错，怎么避免”。

我举几个实际踩过的坑。在“数据库迁移”技能里，我们一开始没有在 checklist 里加“确认迁移脚本可回滚”这一条，结果有一次 AI 代理生成了一个只支持单向迁移的脚本，上线后发现问题想回滚，发现回滚脚本是空的。后来我们把“回滚验证”加进了 checklist，并且要求 AI 在生成迁移脚本时必须同时生成对应的回滚脚本，这个问题就再也没出现过。

在“依赖升级”技能里，pitfalls 里记录了一条：某些包的次版本号升级会引入破坏性变更，不能只看主版本号。这条经验来自一次真实的线上事故，当时 AI 代理把某个库从 2.3 升到 2.4，看起来是次版本升级，结果那个版本改了一个默认配置，导致我们的服务在高峰期超时。把这条写进 pitfalls 之后，AI 代理在升级依赖时会主动去查 changelog，而不是只看版本号。

这些经验如果只存在某个人的脑子里，团队里其他人用 AI 代理时还会再踩一遍。写进技能文件之后，它就变成了团队的共同资产，AI 代理每次执行相关任务时都会自动带上这些提醒。这是我认为技能框架相比普通提示词最大的优势——它让经验可以沉淀和复用。

4. 完整实操流程：从零搭建一套可用的技能框架

4.1 环境准备与目录结构规划

在开始写技能之前，你需要先确认几件事。第一，你的 AI 编程助手支持加载外部技能文件。目前 Claude Code 通过CLAUDE.md和项目内的配置文件支持类似机制，Codex CLI 也有自己的配置方式。第二，你的项目有基本的版本控制，因为技能框架本身也应该被纳入版本管理。第三，你清楚自己最常让 AI 代理做哪几类任务，这决定了你第一批技能应该写什么。

目录结构我建议这样组织：

project-root/ .ai/ skills/ core/ read-before-write.md verify-before-commit.md refactor/ impact-analysis.md incremental-replace.md testing/ test-first.md regression-check.md config.yaml CLAUDE.md

.ai/skills/下按类别分目录，每个技能一个文件。config.yaml里声明哪些技能是核心技能（始终加载），哪些是按需加载。CLAUDE.md里写项目的基本信息和全局规则，并引用config.yaml。这个结构的好处是清晰，新人加入项目时一眼就能看出 AI 代理被配置了哪些能力。

注意：不要把技能文件放在会被构建工具扫描的目录里，比如src/或lib/。这些文件是给 AI 代理读的，不是给运行时用的，混在一起容易造成混淆。

4.2 第一批技能的选择与编写

不要一上来就写二十个技能，那样你维护不过来，AI 代理也加载不过来。我的建议是从三个核心技能开始，这三个技能覆盖了大多数日常任务的基础流程：

第一个是“先读后写”。这个技能解决的是 AI 代理最常见的毛病——不看现有代码就动手改。技能内容很简单：在修改任何文件之前，必须先完整读取该文件，并搜索该文件中定义的函数或类被哪些其他文件引用。执行步骤包括读取目标文件、搜索引用、列出受影响的文件清单、向用户确认理解无误。这个技能应该设为始终加载，因为它适用于几乎所有修改类任务。

第二个是“提交前验证”。这个技能解决的是 AI 代理改完代码不检查就宣布完成的问题。技能内容包括：运行项目配置的 lint 命令、运行相关测试、检查是否有未处理的 TODO 或调试代码、生成改动摘要。这个技能也应该始终加载，但它的执行时机是在任务即将结束时，而不是开始时。

第三个是“增量修改”。这个技能解决的是 AI 代理一次性改太多、出问题难以定位的问题。技能要求把大改动拆成多个小步骤，每步只改一个逻辑单元，每步完成后运行一次快速验证。这个技能适合在重构、迁移、批量替换等场景下按需加载。

这三个技能写下来大概各需要半小时到一小时，但带来的收益是立竿见影的。我自己的项目在引入这三个技能之后，AI 代理改坏代码的概率下降了大概一半，而且每次改动的可审查性明显提升。

4.3 技能加载机制的配置

技能写好了，怎么让 AI 代理知道什么时候加载哪个技能？这需要在config.yaml里配置加载规则。一个典型的配置长这样：

always_load: - core/read-before-write - core/verify-before-commit conditional_load: - skill: refactor/impact-analysis when: - task_contains: ["重构", "重命名", "提取"] - files_changed_count: "> 3" - skill: testing/test-first when: - task_type: ["feature", "bugfix"] - has_test_framework: true skill_dependencies: refactor/incremental-replace: - refactor/impact-analysis testing/regression-check: - testing/test-first

这个配置里，always_load的技能每次会话都会加载，conditional_load的技能根据任务特征动态加载，skill_dependencies声明了技能之间的依赖关系。当 AI 代理加载一个技能时，它会自动把依赖的技能也加载进来。

这里有一个实操细节：条件加载的判断逻辑最好放在 AI 代理的启动脚本里，而不是让模型自己去判断。因为模型判断有随机性，同样的任务描述，这次判断加载了，下次可能就没加载。用脚本做确定性判断，然后把结果作为上下文传给模型，稳定性会高很多。Claude Code 支持通过 hooks 机制在会话启动时执行脚本，Codex CLI 也有类似的 pre-prompt 配置，具体用法可以查各自的官方文档。

4.4 与 Claude Code 和 Codex CLI 的集成方式

Claude Code 的集成相对直接。在项目根目录的CLAUDE.md里，你可以用@语法引用技能文件，比如@.ai/skills/core/read-before-write.md。Claude Code 在启动时会读取CLAUDE.md及其引用的文件，把它们作为系统提示的一部分。对于条件加载的技能，你可以写一个简单的 shell 脚本，根据当前 git 状态或用户输入判断加载哪些技能，然后把结果输出到临时文件，再在CLAUDE.md里引用这个临时文件。

Codex CLI 的集成方式略有不同。它更依赖命令行参数和环境变量。你可以在启动 Codex CLI 时通过--context参数传入技能文件路径，或者把技能内容写入.codex/config文件。Codex CLI 还支持在会话中通过/load命令动态加载技能，这个在需要临时启用某个技能时很方便。

如果你用的是 VS Code 里的 Claude Code 插件，集成方式和终端版基本一致，只是配置文件的路径可能需要在插件设置里指定。我实测下来，把技能文件放在项目根目录的.ai/下，然后在插件设置里把工作目录设为项目根目录，就能正常加载。

提示：不同版本的 Claude Code 和 Codex CLI 对技能加载的支持程度不一样，建议先查一下你所用版本的官方文档，确认支持哪些配置方式。如果某个版本不支持外部文件加载，可以退而求其次，把技能内容直接写在CLAUDE.md里，只是维护起来会麻烦一些。

4.5 一个完整的技能执行实例

为了让你更直观地理解技能框架是怎么工作的，我完整记录一次实际执行过程。任务背景是：我们的项目里有一个formatDate函数，被十几个文件引用，现在需要给它增加一个时区参数，默认值保持现有行为不变。

AI 代理启动后，首先加载了core/read-before-write和core/verify-before-commit两个核心技能。然后根据任务描述中的“修改函数签名”和“被多处引用”，触发了refactor/impact-analysis技能。这个技能要求 AI 先做影响面分析，它执行了以下步骤：

1. 读取formatDate函数定义，确认当前签名和实现
2. 在整个项目中搜索formatDate的调用点，找到 14 个文件、23 处调用
3. 检查每处调用是否传入了日期参数，确认哪些调用会受新参数影响
4. 生成影响面报告，列出所有需要检查的文件和调用点
5. 向用户展示报告，确认是否继续

我确认之后，AI 代理加载了refactor/incremental-replace技能，开始逐个文件修改。每修改一个文件，它都会运行该文件相关的测试，确认没有破坏现有行为。全部修改完成后，core/verify-before-commit技能被触发，AI 代理运行了完整的测试套件和 lint 检查，生成了改动摘要，包括修改了哪些文件、每个文件改了什么、测试结果如何。

整个过程大概花了八分钟，期间我只在影响面报告确认时介入了一次。如果没有技能框架，同样的任务 AI 代理可能会直接开始改，改到一半发现某个调用点传参方式特殊，又回头调整，来回折腾可能二十分钟还不一定改对。这个对比让我确信，技能框架带来的效率提升是实实在在的。

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

5.1 技能不生效或加载失败的排查思路

技能框架用起来之后，最常见的问题就是“我明明写了技能，但 AI 代理好像没按技能执行”。这个问题通常有几个原因，我按排查顺序列一下。

第一个要检查的是技能文件是否被正确引用。如果你用的是@引用语法，确认路径是否正确，文件是否存在。有时候文件名大小写不匹配，在 macOS 上可能没问题，到了 Linux 环境就加载不上了。第二个要检查的是触发条件是否满足。你可以在 AI 代理的启动日志里看它加载了哪些技能，如果目标技能不在列表里，说明触发条件没匹配上。这时候可以临时把技能改成始终加载，确认技能内容本身没问题，然后再回去调触发条件。

第三个可能的原因是技能内容太长，被模型忽略了。前面说过，上下文窗口是有限资源，如果你的技能文件写了几千字，模型可能只读了开头就跳过了。解决办法是把技能拆成多个小文件，每个文件只讲一件事，通过依赖关系组合起来。单个技能文件的长度建议控制在 500 字以内，超过这个长度就应该考虑拆分。

还有一个比较隐蔽的原因是技能之间的冲突。比如两个技能都要求在任务开始时执行某个步骤，但步骤内容不一样，AI 代理就不知道该听谁的。这种情况需要在config.yaml里明确技能的优先级，或者在技能文件里声明互斥关系。

5.2 技能执行到一半卡住的处理方式

有时候 AI 代理会加载了技能，执行了几步之后停在那里不动了。这种情况通常是因为某一步的验证条件没有满足，AI 代理在等待一个它认为应该出现但没出现的结果。比如“运行测试”这一步，如果测试命令因为环境问题没有输出预期格式的结果，AI 代理可能就卡在“等待测试结果”的状态。

处理方式分两步。短期解决是在当前会话里直接告诉 AI 代理“跳过这一步，继续执行后面的步骤”，或者“这一步的验证条件改为 XXX”。长期解决是修改技能文件，把这一步的验证条件写得更宽松，或者增加一个超时和降级策略。比如“运行测试”这一步可以改成“运行测试，如果 30 秒内没有输出则记录超时并继续”。

我自己的经验是，技能里的每一步都应该有一个明确的“失败后怎么办”的说明。这个说明可以写在步骤描述里，也可以单独用一个on_failure字段。没有失败处理机制的技能，在实际使用中很容易变成“一卡就卡死”的状态。

5.3 多技能并行时的优先级冲突

当多个技能同时被触发时，它们的执行顺序和优先级需要明确。比如“测试先行”技能要求在修改代码前写测试，“增量修改”技能要求把改动拆成小步，这两个技能同时加载时，是先写测试还是先拆步骤？如果没有明确规则，AI 代理可能会随机选一个顺序，导致流程混乱。

解决办法是在config.yaml里定义技能的优先级数值，数值高的先执行。或者更简单的方式，在技能文件里声明before和after关系，比如“测试先行”声明before: refactor/incremental-replace，表示它应该在增量修改之前执行。AI 代理在加载技能时会解析这些关系，生成一个拓扑排序后的执行顺序。

还有一种情况是两个技能确实无法同时满足，比如一个要求“每次只改一个文件”，另一个要求“批量替换所有引用”。这时候需要在配置里声明互斥，让 AI 代理在加载时二选一，或者向用户询问该用哪个。互斥声明可以写成conflicts_with: [skill-name]，AI 代理在检测到冲突时会暂停并请求用户决策。

5.4 技能框架与项目现有规范的融合

很多团队已经有自己的代码规范和开发流程，引入技能框架时需要考虑怎么和现有规范融合，而不是另起一套。我的建议是，技能框架应该作为现有规范的“执行层”，而不是替代品。也就是说，你的代码规范还是写在原来的地方，技能文件负责的是“怎么让 AI 代理遵守这些规范”。

具体做法是在技能文件里引用现有的规范文档。比如“提交前验证”技能里可以写“运行npm run lint，lint 规则以.eslintrc为准”。这样规范更新时只需要改一处，技能文件不用动。另外，如果团队有 code review 清单，可以直接把清单内容转成技能的 checklist 字段，这样 AI 代理在提交前做的自检和人工 review 的检查项就对齐了。

我见过一个团队的做法很聪明：他们把技能框架和 CI 流水线打通，AI 代理在本地执行技能时用的检查命令，和 CI 上跑的命令是同一套。这样本地通过了，CI 基本也能通过，减少了“本地没问题、推上去挂了”的情况。这个思路值得借鉴，核心原则就是不要让技能框架成为一套独立的、和现有流程脱节的系统。

5.5 常见问题速查表

这张表里的问题我都实际遇到过，其中“技能内容被忽略”是最难排查的，因为表面上技能加载了，AI 代理也说它读了，但执行时就是不按技能来。后来我发现是技能文件写得太长，模型只读了前三分之一。把文件拆短之后问题就解决了。这个坑提醒我，写技能文件时要像写代码一样，保持单一职责，一个文件只做一件事。

6. 技能框架的扩展与团队协作实践

6.1 从个人使用到团队共享的过渡

个人用技能框架和团队用是两回事。个人用的时候，技能文件怎么写、怎么组织，自己清楚就行。团队用的时候，你需要考虑版本管理、变更评审、新人上手这些问题。我的建议是，技能文件应该和代码一样走 pull request 流程，任何修改都需要至少一个人 review。

review 的重点不是技能文件的格式，而是技能定义的流程是否合理、触发条件是否准确、检查清单是否完整。我见过一个团队在 review 时发现，某个技能的触发条件写得太宽，导致 AI 代理在写文档时也加载了“测试先行”技能，白白浪费了上下文。这种问题只有通过 review 才能发现。

另外，团队共享的技能框架需要一个“技能目录”文档，列出所有可用技能、每个技能的用途、触发条件、依赖关系。这个文档可以自动从技能文件生成，避免手动维护导致的不一致。新人加入时，先读这个目录，了解团队给 AI 代理配置了哪些能力，然后再去看具体技能文件。

6.2 技能库的持续迭代与经验沉淀

技能框架最大的价值在于它能积累经验，但前提是你真的在持续更新它。我的做法是，每次 AI 代理执行任务出了问题，我都会问自己：这个问题能不能通过修改技能来避免？如果能，就当场改技能文件，而不是下次遇到同样问题时再临时提醒 AI。

比如有一次 AI 代理在修改一个配置文件时，没有注意到该文件被另一个服务以只读方式挂载，改完之后另一个服务启动失败了。这个问题后来被写进了“配置文件修改”技能的 pitfalls 里：修改配置文件前，先确认该文件是否被其他服务引用或挂载。这条经验写进去之后，类似的问题就再也没出现过。

迭代频率上，我建议每周花十五分钟回顾一下这周 AI 代理出的问题，把共性的问题转化成技能更新。不要攒着，攒到最后就忘了。技能库的质量不在于数量，而在于每一条都是真实踩坑得来的，这样的技能 AI 代理执行起来才有“经验感”。

6.3 技能框架的边界与不适用场景

说了这么多技能框架的好处，也得说说它不适合什么场景。首先，探索性任务不适合。比如你让 AI 代理去调研一个新技术方案，这种任务没有明确的步骤和验证条件，硬套技能框架反而会限制它的发挥。其次，一次性小任务不适合。改个错别字、调个格式，加载技能的开销比任务本身还大。最后，高度依赖外部状态的任务不适合。比如需要人工在某个系统里操作之后才能继续的任务，技能框架没法处理这种等待和交互。

判断标准很简单：如果一个任务你让一个新人来做，你需要给他写一份详细的操作手册，那它就适合用技能框架。如果你只需要说一句“把这个改一下”，那就不需要。技能框架是给复杂任务用的，不是给所有任务用的。这个边界想清楚了，你就不会陷入“什么都要写个技能”的过度工程陷阱。

6.4 与本地模型和第三方 API 的配合

有些团队出于成本或数据考虑，会用本地模型或者第三方 API 来驱动 AI 代理。这种情况下技能框架依然适用，但需要注意几点。第一，本地模型的上下文窗口通常比云端模型小，技能文件要写得更精简，加载的技能数量要控制得更严格。第二，不同模型对结构化指令的遵循程度不一样，技能里的步骤描述要尽量用明确的动词和可验证的条件，避免模糊表达。第三，如果用的是第三方 API，要确认它是否支持系统提示词和外部文件引用，有些 API 只支持单轮对话，那就没法用技能框架。

我实测过用本地模型跑技能框架，效果比预期好。关键是把技能文件写得更“直白”，少用抽象概念，多用具体命令和文件路径。本地模型在遵循明确指令方面表现不错，只是在需要灵活判断的地方会弱一些。所以如果你的场景以流程性任务为主，本地模型加技能框架是一个性价比很高的组合。

7. 我在这套框架上踩过的坑与最终建议

回过头看，我在技能框架上踩的坑大概可以分成三类。第一类是过度设计，一开始写了太多技能，每个技能又写得太细，结果 AI 代理加载了一堆用不上的技能，反而拖慢了执行速度。后来我砍掉了三分之二的技能，只保留最核心的几个，效果反而更好。第二类是触发条件写得太模糊，导致技能该加载的时候没加载，不该加载的时候乱加载。后来我改用可观测的信号来定义触发条件，问题就解决了。第三类是忘了给技能写失败处理，导致 AI 代理执行到某一步卡住时不知道怎么办，只能干等。后来我在每个技能里都加了on_failure说明，明确告诉 AI 代理失败后是重试、跳过还是求助。

如果让我给刚接触这套框架的人一条建议，我会说：从最小的技能开始，只写你每天都在重复的那件事。不要一上来就追求大而全的框架，先写一个“先读后写”技能，用一周，感受一下它带来的变化。然后根据实际遇到的问题，再写第二个、第三个。技能框架的价值不在于它有多完整，而在于它是否真的解决了你工作中的痛点。我见过太多人花了两天搭了一套看起来很漂亮的框架，结果用了一周就放弃了，原因就是框架太复杂，维护成本超过了收益。

最后分享一个我最近在用的技巧：我会在每周五下午花十分钟，把这一周 AI 代理犯的错整理成一条条“教训”，然后挑其中最有共性的两三条，更新到对应的技能文件里。这个习惯坚持了两个月之后，我明显感觉到 AI 代理在项目里的表现越来越“稳”了，很多以前需要我反复提醒的事情，现在它自己就会注意。这种“越用越顺手”的感觉，是技能框架最让我满意的地方。