1. 拆解 superpowers它到底想解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子就会发现它其实是一个面向agentic skills framework的软件工程方法论实践集合。简单说它试图回答一个很具体的问题当我们把 Claude Code、Codex CLI 这类终端里的 AI 编程助手当成日常工具之后怎么让它们不只是“能跑”而是“跑得稳、跑得可复现、跑得能积累”我自己的理解是superpowers 更像是一套围绕 AI 编程代理构建的“技能框架 工作流约定”。它不绑定某一个具体模型也不要求你必须用某个特定平台。你可以把它看成一份写给开发者的操作手册哪些任务适合交给代理去做哪些必须自己盯着上下文怎么组织命令怎么拆解失败之后怎么回滚做完之后怎么把经验沉淀成下一次可以直接复用的技能模块。这些内容听起来有点抽象但落到实际项目里每一个点都对应着真实的痛点。举个很常见的场景。你用 Claude Code 在终端里让它帮你重构一个模块第一次它改得不错第二次换个需求再让它改它可能就把之前的结构又打乱了。问题不在于模型能力不够而在于你没有给它一个稳定的“技能边界”和“验收标准”。superpowers 这类框架的价值就是把这些边界和标准显式地写出来让代理每次执行时都有据可依。它适合谁我认为三类人最应该关注一是已经把 AI 编程助手接入日常开发流程的工程师二是正在搭建团队内部 AI 辅助规范的技术负责人三是想从“会用”进阶到“用得好”的独立开发者。2. 核心设计思路为什么是技能框架而不是提示词合集2.1 从“提示词工程”到“技能工程”的转变早期大家用 AI 编程助手习惯攒一堆提示词模板遇到什么任务就翻出来改一改。这种做法在单次任务里有效但一旦任务变多、协作变复杂就会暴露两个问题第一提示词之间没有依赖关系无法组合第二提示词没有版本管理改坏了很难回退。superpowers 的思路是把“提示词”升级成“技能”。一个技能不只是几句话它包含触发条件、输入输出约定、执行步骤、验收标准甚至包括失败之后的降级方案。这个转变背后的逻辑其实很朴素。你想想一个刚入职的工程师你不会只给他一句“把这个功能做了”你会告诉他背景是什么、边界在哪里、做完怎么验证。技能框架就是把这种“带人”的方式标准化只不过对象换成了 AI 代理。这样做的好处是技能可以被复用、被测试、被迭代。今天你写了一个“数据库迁移”技能明天遇到类似任务直接调用就行不需要重新组织语言。2.2 为什么选择终端优先而不是 IDE 优先从热词里能看到大量关于 Claude Code、Codex CLI、VS Code 配置的讨论。superpowers 的实践路径明显偏向终端优先。这不是说 IDE 不好而是终端环境有几个天然优势第一命令和输出都是文本容易被代理理解和记录第二终端里的操作更接近“原子步骤”一个命令做一件事方便拆解和回滚第三终端环境更容易做自动化串联比如把格式化、测试、提交串成一条流水线。我在实际使用中发现终端优先还有一个隐性好处它强迫你把任务想清楚。在 IDE 里点来点去很多操作是隐式的在终端里你必须写出具体命令。这个“写出来”的过程本身就是一次需求澄清。superpowers 把这一点放大要求每个技能都明确写出执行命令和预期输出这样代理执行时就不会“自由发挥”。2.3 框架的边界它不做什么有一点需要提前说清楚superpowers 不是模型不是插件也不是某个平台的专属功能。它不会帮你自动安装 Claude Code也不会替你解决账号注册或者网络环境的问题。它是一层方法论落在具体工具之上。你可以用 Claude Code 来执行它也可以用 Codex CLI 来执行它甚至可以用其他支持终端调用的模型来执行。它的价值在于“怎么组织工作”而不是“用什么工具工作”。理解这一点很重要否则你会在工具选型上浪费很多时间。3. 核心细节解析一个技能模块应该包含什么3.1 技能描述与触发条件一个可用的技能模块第一件事是写清楚“什么时候用它”。这听起来简单但很多人会忽略。比如你写了一个“修复测试失败”的技能如果没有触发条件代理可能在代码还没写完的时候就跑去修测试。触发条件应该尽量具体包含前置状态和用户意图。例如“当测试命令返回非零退出码且用户明确要求修复测试时加载本技能。”这种描述比“用于修复测试”要可靠得多。触发条件还有一个作用是防止技能被滥用。AI 代理有时候会过度积极看到一点相关信号就调用某个技能。明确的触发条件相当于一道闸门只有满足条件才放行。我在自己的项目里会把触发条件写成类似配置的格式方便代理解析也方便自己复查。3.2 输入输出约定与验收标准技能的执行结果必须可验证。superpowers 强调验收标准要前置也就是说在技能开始执行之前就要定义好“什么样算完成”。比如一个“添加日志”的技能验收标准可能是指定模块的关键路径上出现日志语句日志级别符合项目规范运行测试时日志不导致失败。这些标准写出来之后代理执行时就有了目标你验收时也有了依据。输入输出约定则是让技能之间可以串联。一个技能的输出可能是另一个技能的输入。比如“生成迁移脚本”技能输出一个文件路径“执行迁移”技能接收这个路径。如果没有约定代理每次都要重新推断容易出错。我通常会用简单的结构化文本描述输入输出不追求复杂格式够用就行。3.3 执行步骤与回滚方案执行步骤要拆到“可观察”的粒度。什么叫可观察就是每一步执行完你都能通过命令输出或者文件变化判断它是否成功。比如“修改配置文件”这一步执行完应该能看到文件内容变化“运行测试”这一步执行完应该能看到测试结果。如果一步里包含太多操作失败了很难定位。回滚方案是很多人会漏掉的部分。AI 代理执行任务时失败是常态不是异常。没有回滚方案一次失败可能留下半成品状态影响后续操作。superpowers 的做法是要求每个技能在执行前记录当前状态比如用版本控制做快照或者把关键文件备份到临时目录。这样失败之后可以快速恢复而不是手动一点点清理。提示回滚方案不需要很复杂git stash 或者复制一份文件通常就够了。关键是要有而不是追求完美。4. 实操过程从零搭建一个可用的技能工作流4.1 环境准备与工具确认在开始之前你需要确认几件事。第一你有一个可以执行终端命令的 AI 编程助手Claude Code 或者 Codex CLI 都可以。第二你的项目在版本控制之下这是回滚的基础。第三你清楚自己最常重复的任务是什么这是你第一个技能模块的候选。我不建议一上来就搭一个大而全的框架。先选一个你每周至少做三次的小任务比如“格式化代码并运行 lint”或者“根据错误日志定位问题”。把这个任务写成技能模块跑通一遍再考虑扩展。这样做的原因是小任务反馈快你能迅速发现框架设计里的问题调整成本低。4.2 编写第一个技能模块假设我们选的任务是“运行测试并汇总失败信息”。技能模块可以这样写## 技能测试失败汇总 ### 触发条件 - 用户要求运行测试 - 当前目录存在测试配置文件 ### 输入 - 测试命令默认npm test ### 执行步骤 1. 执行测试命令捕获输出 2. 如果退出码为 0报告“全部通过” 3. 如果退出码非 0提取失败用例名称和错误摘要 4. 将失败信息写入 test-failures.md ### 验收标准 - test-failures.md 存在 - 文件中包含至少一个失败用例名称 - 文件内容不超过 200 行 ### 回滚方案 - 删除 test-failures.md这个模块很简单但它包含了触发条件、输入、步骤、验收和回滚。你可以把它放在项目根目录的 skills 文件夹里然后在跟代理对话时明确说“加载测试失败汇总技能”。代理会按照这个结构执行而不是自由发挥。4.3 参数选择与命令拆解的实际考量在执行步骤里命令的写法很关键。以测试命令为例不同项目的测试命令不一样有的用 npm test有的用 pytest有的用 go test。如果你把命令写死技能就无法复用。更好的做法是把命令作为输入参数技能里只写“执行输入中指定的测试命令”。这样同一个技能可以适配不同项目。另一个细节是输出处理。测试输出可能很长直接全部塞给代理会占用大量上下文。我通常会在技能里加一步“提取关键信息”比如只保留失败用例名称和错误类型把完整输出写到文件里备查。这样代理看到的上下文更干净判断也更准确。4.4 实操现场记录一次完整的技能执行我拿一个真实的小项目试了一遍。项目是一个 Node.js 服务测试用 Jest。我先把上面的技能模块放到 skills 目录然后对 Claude Code 说“加载测试失败汇总技能测试命令是 npx jest。”代理先读取了技能文件然后执行命令。第一次执行时有两个用例失败。代理按照步骤提取了失败用例名称和错误摘要写入了 test-failures.md。我检查了文件内容符合验收标准。然后我修复了其中一个用例再次执行技能文件更新为只剩一个失败用例。整个过程没有出现代理乱改代码的情况因为技能里没有授权它修改代码它只做了汇总。这次实操让我确认了一件事技能模块的边界越清晰代理的行为越可控。如果你在技能里写“修复失败的测试”代理就会尝试改代码风险立刻上升。所以第一个技能最好选只读操作先建立信任再逐步放开写操作。5. 常见问题与排查技巧实录5.1 代理不按技能执行怎么办这是最常见的问题。原因通常有三个第一触发条件写得太模糊代理觉得当前场景不匹配第二技能文件没有被正确加载代理根本不知道有这个技能第三代理的上下文里已经有其他指令优先级冲突。排查顺序建议从加载开始确认代理能读到技能文件然后检查触发条件看是否过于严格或过于宽松最后检查对话历史看是否有冲突指令。我自己的经验是在对话开头明确说“本次对话只使用以下技能”比让代理自己判断要可靠。代理的判断能力在复杂场景下并不稳定显式指定能减少很多意外。5.2 技能执行到一半失败怎么恢复如果技能有回滚方案直接执行回滚然后重新加载技能。如果没有回滚方案先手动恢复到执行前的状态再补上回滚方案。这里的关键是不要在半成品状态上继续叠加操作那样只会让问题更复杂。我踩过一次坑代理修改了配置文件之后失败我没有回滚就直接让它重试结果配置文件里出现了重复内容排查了很久。从那以后我要求每个写操作技能必须先做备份。5.3 多个技能之间如何避免冲突当你有多个技能时冲突主要出现在两个方面文件操作重叠和上下文占用。文件操作重叠可以通过约定目录来避免比如每个技能只操作自己负责的目录。上下文占用则需要控制技能输出的信息量尽量让技能输出结构化摘要而不是原始日志。我通常会把技能输出限制在 50 行以内超出部分写到文件里代理只读摘要。下面这张表整理了我遇到过的典型问题和处理方式可以直接对照排查问题现象可能原因处理方式代理忽略技能技能未加载或触发条件不匹配显式指定技能放宽触发条件执行结果不符合预期验收标准不明确补充可验证的验收条件失败后状态混乱缺少回滚方案执行前备份失败后先回滚技能之间互相干扰文件操作重叠约定独立工作目录上下文被占满技能输出信息过多输出摘要详细内容写文件5.4 关于工具链选择的几点个人建议Claude Code 和 Codex CLI 我都用过一段时间。Claude Code 在理解复杂技能描述方面表现更稳适合执行步骤较多的技能Codex CLI 在命令执行和文件操作上更直接适合步骤简单的技能。如果你刚开始搭建我建议先用一个工具跑通流程不要同时折腾多个。等技能模块稳定了再考虑跨工具复用。另外关于本地模型接入热词里提到不少相关讨论。我的看法是本地模型适合对隐私要求高、任务相对固定的场景。如果你的技能模块需要频繁调用外部命令和读写文件本地模型的工具调用能力需要仔细验证。不要因为“本地”就默认它更可控实际表现取决于具体模型和配置。6. 技能框架的扩展与长期维护6.1 从单技能到技能库的演进路径当你有了三五个稳定运行的技能之后就可以考虑把它们组织成技能库。技能库的核心是索引和分类。索引让代理能快速找到需要的技能分类让人类维护者能快速定位。我自己的做法是按任务类型分目录比如“代码质量”“测试”“部署”“文档”每个目录下放对应的技能文件。然后在根目录放一个 index.md列出所有技能的名称、触发条件和文件路径。这个演进路径不需要一步到位。你可以先手动维护索引等技能数量超过二十个再考虑自动化生成。过早自动化会增加维护成本而且你还不清楚自己的分类习惯。6.2 技能版本管理与迭代技能也是代码应该纳入版本管理。每次修改技能都要写清楚改了什么、为什么改。我通常会在技能文件顶部加一个变更记录格式很简单日期、修改人、修改内容。这样当技能行为发生变化时能快速定位到是哪次修改导致的。迭代技能时建议保留旧版本一段时间。新版本可能在某些场景下表现不如旧版本保留旧版本可以快速切换。我一般会保留最近三个版本超过三个再清理。6.3 团队协作中的技能共享如果团队多人使用同一套技能库需要约定一些规则。第一技能文件命名要统一建议用“动词-名词”格式比如“run-tests”“fix-lint”。第二修改技能需要经过评审避免个人偏好影响团队。第三技能库要有明确的负责人负责合并冲突和清理过期技能。团队协作里最容易出问题的是“私有技能”和“公共技能”的边界。我的建议是任何技能在稳定运行两周之后都应该考虑是否提升为公共技能。长期停留在私有状态会导致重复建设和知识孤岛。6.4 技能框架的长期价值在哪里用了一段时间之后我最大的体会是技能框架的价值不在于让 AI 做更多事而在于让 AI 做的事更可预期。可预期意味着你可以放心地把重复任务交出去把精力留给真正需要判断力的工作。这个转变不会一夜发生但随着技能库的积累你会发现自己跟代理的协作越来越顺返工越来越少。最后分享一个小技巧每隔一段时间回顾一下你的技能库把那些超过一个月没用的技能归档。技能库不是越大越好保持精简才能让代理快速定位。我现在的技能库维持在十五个左右每个都经过多次迭代用起来很稳。 
长河君 · 2026/10/7 23:06:41 · 阅读 1.2k superpowers 技能框架：AI 编程代理的工程化实践指南
1. 拆解 superpowers它到底想解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子就会发现它其实是一个面向agentic skills framework的软件工程方法论实践集合。简单说它试图回答一个很具体的问题当我们把 Claude Code、Codex CLI 这类终端里的 AI 编程助手当成日常工具之后怎么让它们不只是“能跑”而是“跑得稳、跑得可复现、跑得能积累”我自己的理解是superpowers 更像是一套围绕 AI 编程代理构建的“技能框架 工作流约定”。它不绑定某一个具体模型也不要求你必须用某个特定平台。你可以把它看成一份写给开发者的操作手册哪些任务适合交给代理去做哪些必须自己盯着上下文怎么组织命令怎么拆解失败之后怎么回滚做完之后怎么把经验沉淀成下一次可以直接复用的技能模块。这些内容听起来有点抽象但落到实际项目里每一个点都对应着真实的痛点。举个很常见的场景。你用 Claude Code 在终端里让它帮你重构一个模块第一次它改得不错第二次换个需求再让它改它可能就把之前的结构又打乱了。问题不在于模型能力不够而在于你没有给它一个稳定的“技能边界”和“验收标准”。superpowers 这类框架的价值就是把这些边界和标准显式地写出来让代理每次执行时都有据可依。它适合谁我认为三类人最应该关注一是已经把 AI 编程助手接入日常开发流程的工程师二是正在搭建团队内部 AI 辅助规范的技术负责人三是想从“会用”进阶到“用得好”的独立开发者。2. 核心设计思路为什么是技能框架而不是提示词合集2.1 从“提示词工程”到“技能工程”的转变早期大家用 AI 编程助手习惯攒一堆提示词模板遇到什么任务就翻出来改一改。这种做法在单次任务里有效但一旦任务变多、协作变复杂就会暴露两个问题第一提示词之间没有依赖关系无法组合第二提示词没有版本管理改坏了很难回退。superpowers 的思路是把“提示词”升级成“技能”。一个技能不只是几句话它包含触发条件、输入输出约定、执行步骤、验收标准甚至包括失败之后的降级方案。这个转变背后的逻辑其实很朴素。你想想一个刚入职的工程师你不会只给他一句“把这个功能做了”你会告诉他背景是什么、边界在哪里、做完怎么验证。技能框架就是把这种“带人”的方式标准化只不过对象换成了 AI 代理。这样做的好处是技能可以被复用、被测试、被迭代。今天你写了一个“数据库迁移”技能明天遇到类似任务直接调用就行不需要重新组织语言。2.2 为什么选择终端优先而不是 IDE 优先从热词里能看到大量关于 Claude Code、Codex CLI、VS Code 配置的讨论。superpowers 的实践路径明显偏向终端优先。这不是说 IDE 不好而是终端环境有几个天然优势第一命令和输出都是文本容易被代理理解和记录第二终端里的操作更接近“原子步骤”一个命令做一件事方便拆解和回滚第三终端环境更容易做自动化串联比如把格式化、测试、提交串成一条流水线。我在实际使用中发现终端优先还有一个隐性好处它强迫你把任务想清楚。在 IDE 里点来点去很多操作是隐式的在终端里你必须写出具体命令。这个“写出来”的过程本身就是一次需求澄清。superpowers 把这一点放大要求每个技能都明确写出执行命令和预期输出这样代理执行时就不会“自由发挥”。2.3 框架的边界它不做什么有一点需要提前说清楚superpowers 不是模型不是插件也不是某个平台的专属功能。它不会帮你自动安装 Claude Code也不会替你解决账号注册或者网络环境的问题。它是一层方法论落在具体工具之上。你可以用 Claude Code 来执行它也可以用 Codex CLI 来执行它甚至可以用其他支持终端调用的模型来执行。它的价值在于“怎么组织工作”而不是“用什么工具工作”。理解这一点很重要否则你会在工具选型上浪费很多时间。3. 核心细节解析一个技能模块应该包含什么3.1 技能描述与触发条件一个可用的技能模块第一件事是写清楚“什么时候用它”。这听起来简单但很多人会忽略。比如你写了一个“修复测试失败”的技能如果没有触发条件代理可能在代码还没写完的时候就跑去修测试。触发条件应该尽量具体包含前置状态和用户意图。例如“当测试命令返回非零退出码且用户明确要求修复测试时加载本技能。”这种描述比“用于修复测试”要可靠得多。触发条件还有一个作用是防止技能被滥用。AI 代理有时候会过度积极看到一点相关信号就调用某个技能。明确的触发条件相当于一道闸门只有满足条件才放行。我在自己的项目里会把触发条件写成类似配置的格式方便代理解析也方便自己复查。3.2 输入输出约定与验收标准技能的执行结果必须可验证。superpowers 强调验收标准要前置也就是说在技能开始执行之前就要定义好“什么样算完成”。比如一个“添加日志”的技能验收标准可能是指定模块的关键路径上出现日志语句日志级别符合项目规范运行测试时日志不导致失败。这些标准写出来之后代理执行时就有了目标你验收时也有了依据。输入输出约定则是让技能之间可以串联。一个技能的输出可能是另一个技能的输入。比如“生成迁移脚本”技能输出一个文件路径“执行迁移”技能接收这个路径。如果没有约定代理每次都要重新推断容易出错。我通常会用简单的结构化文本描述输入输出不追求复杂格式够用就行。3.3 执行步骤与回滚方案执行步骤要拆到“可观察”的粒度。什么叫可观察就是每一步执行完你都能通过命令输出或者文件变化判断它是否成功。比如“修改配置文件”这一步执行完应该能看到文件内容变化“运行测试”这一步执行完应该能看到测试结果。如果一步里包含太多操作失败了很难定位。回滚方案是很多人会漏掉的部分。AI 代理执行任务时失败是常态不是异常。没有回滚方案一次失败可能留下半成品状态影响后续操作。superpowers 的做法是要求每个技能在执行前记录当前状态比如用版本控制做快照或者把关键文件备份到临时目录。这样失败之后可以快速恢复而不是手动一点点清理。提示回滚方案不需要很复杂git stash 或者复制一份文件通常就够了。关键是要有而不是追求完美。4. 实操过程从零搭建一个可用的技能工作流4.1 环境准备与工具确认在开始之前你需要确认几件事。第一你有一个可以执行终端命令的 AI 编程助手Claude Code 或者 Codex CLI 都可以。第二你的项目在版本控制之下这是回滚的基础。第三你清楚自己最常重复的任务是什么这是你第一个技能模块的候选。我不建议一上来就搭一个大而全的框架。先选一个你每周至少做三次的小任务比如“格式化代码并运行 lint”或者“根据错误日志定位问题”。把这个任务写成技能模块跑通一遍再考虑扩展。这样做的原因是小任务反馈快你能迅速发现框架设计里的问题调整成本低。4.2 编写第一个技能模块假设我们选的任务是“运行测试并汇总失败信息”。技能模块可以这样写## 技能测试失败汇总 ### 触发条件 - 用户要求运行测试 - 当前目录存在测试配置文件 ### 输入 - 测试命令默认npm test ### 执行步骤 1. 执行测试命令捕获输出 2. 如果退出码为 0报告“全部通过” 3. 如果退出码非 0提取失败用例名称和错误摘要 4. 将失败信息写入 test-failures.md ### 验收标准 - test-failures.md 存在 - 文件中包含至少一个失败用例名称 - 文件内容不超过 200 行 ### 回滚方案 - 删除 test-failures.md这个模块很简单但它包含了触发条件、输入、步骤、验收和回滚。你可以把它放在项目根目录的 skills 文件夹里然后在跟代理对话时明确说“加载测试失败汇总技能”。代理会按照这个结构执行而不是自由发挥。4.3 参数选择与命令拆解的实际考量在执行步骤里命令的写法很关键。以测试命令为例不同项目的测试命令不一样有的用 npm test有的用 pytest有的用 go test。如果你把命令写死技能就无法复用。更好的做法是把命令作为输入参数技能里只写“执行输入中指定的测试命令”。这样同一个技能可以适配不同项目。另一个细节是输出处理。测试输出可能很长直接全部塞给代理会占用大量上下文。我通常会在技能里加一步“提取关键信息”比如只保留失败用例名称和错误类型把完整输出写到文件里备查。这样代理看到的上下文更干净判断也更准确。4.4 实操现场记录一次完整的技能执行我拿一个真实的小项目试了一遍。项目是一个 Node.js 服务测试用 Jest。我先把上面的技能模块放到 skills 目录然后对 Claude Code 说“加载测试失败汇总技能测试命令是 npx jest。”代理先读取了技能文件然后执行命令。第一次执行时有两个用例失败。代理按照步骤提取了失败用例名称和错误摘要写入了 test-failures.md。我检查了文件内容符合验收标准。然后我修复了其中一个用例再次执行技能文件更新为只剩一个失败用例。整个过程没有出现代理乱改代码的情况因为技能里没有授权它修改代码它只做了汇总。这次实操让我确认了一件事技能模块的边界越清晰代理的行为越可控。如果你在技能里写“修复失败的测试”代理就会尝试改代码风险立刻上升。所以第一个技能最好选只读操作先建立信任再逐步放开写操作。5. 常见问题与排查技巧实录5.1 代理不按技能执行怎么办这是最常见的问题。原因通常有三个第一触发条件写得太模糊代理觉得当前场景不匹配第二技能文件没有被正确加载代理根本不知道有这个技能第三代理的上下文里已经有其他指令优先级冲突。排查顺序建议从加载开始确认代理能读到技能文件然后检查触发条件看是否过于严格或过于宽松最后检查对话历史看是否有冲突指令。我自己的经验是在对话开头明确说“本次对话只使用以下技能”比让代理自己判断要可靠。代理的判断能力在复杂场景下并不稳定显式指定能减少很多意外。5.2 技能执行到一半失败怎么恢复如果技能有回滚方案直接执行回滚然后重新加载技能。如果没有回滚方案先手动恢复到执行前的状态再补上回滚方案。这里的关键是不要在半成品状态上继续叠加操作那样只会让问题更复杂。我踩过一次坑代理修改了配置文件之后失败我没有回滚就直接让它重试结果配置文件里出现了重复内容排查了很久。从那以后我要求每个写操作技能必须先做备份。5.3 多个技能之间如何避免冲突当你有多个技能时冲突主要出现在两个方面文件操作重叠和上下文占用。文件操作重叠可以通过约定目录来避免比如每个技能只操作自己负责的目录。上下文占用则需要控制技能输出的信息量尽量让技能输出结构化摘要而不是原始日志。我通常会把技能输出限制在 50 行以内超出部分写到文件里代理只读摘要。下面这张表整理了我遇到过的典型问题和处理方式可以直接对照排查问题现象可能原因处理方式代理忽略技能技能未加载或触发条件不匹配显式指定技能放宽触发条件执行结果不符合预期验收标准不明确补充可验证的验收条件失败后状态混乱缺少回滚方案执行前备份失败后先回滚技能之间互相干扰文件操作重叠约定独立工作目录上下文被占满技能输出信息过多输出摘要详细内容写文件5.4 关于工具链选择的几点个人建议Claude Code 和 Codex CLI 我都用过一段时间。Claude Code 在理解复杂技能描述方面表现更稳适合执行步骤较多的技能Codex CLI 在命令执行和文件操作上更直接适合步骤简单的技能。如果你刚开始搭建我建议先用一个工具跑通流程不要同时折腾多个。等技能模块稳定了再考虑跨工具复用。另外关于本地模型接入热词里提到不少相关讨论。我的看法是本地模型适合对隐私要求高、任务相对固定的场景。如果你的技能模块需要频繁调用外部命令和读写文件本地模型的工具调用能力需要仔细验证。不要因为“本地”就默认它更可控实际表现取决于具体模型和配置。6. 技能框架的扩展与长期维护6.1 从单技能到技能库的演进路径当你有了三五个稳定运行的技能之后就可以考虑把它们组织成技能库。技能库的核心是索引和分类。索引让代理能快速找到需要的技能分类让人类维护者能快速定位。我自己的做法是按任务类型分目录比如“代码质量”“测试”“部署”“文档”每个目录下放对应的技能文件。然后在根目录放一个 index.md列出所有技能的名称、触发条件和文件路径。这个演进路径不需要一步到位。你可以先手动维护索引等技能数量超过二十个再考虑自动化生成。过早自动化会增加维护成本而且你还不清楚自己的分类习惯。6.2 技能版本管理与迭代技能也是代码应该纳入版本管理。每次修改技能都要写清楚改了什么、为什么改。我通常会在技能文件顶部加一个变更记录格式很简单日期、修改人、修改内容。这样当技能行为发生变化时能快速定位到是哪次修改导致的。迭代技能时建议保留旧版本一段时间。新版本可能在某些场景下表现不如旧版本保留旧版本可以快速切换。我一般会保留最近三个版本超过三个再清理。6.3 团队协作中的技能共享如果团队多人使用同一套技能库需要约定一些规则。第一技能文件命名要统一建议用“动词-名词”格式比如“run-tests”“fix-lint”。第二修改技能需要经过评审避免个人偏好影响团队。第三技能库要有明确的负责人负责合并冲突和清理过期技能。团队协作里最容易出问题的是“私有技能”和“公共技能”的边界。我的建议是任何技能在稳定运行两周之后都应该考虑是否提升为公共技能。长期停留在私有状态会导致重复建设和知识孤岛。6.4 技能框架的长期价值在哪里用了一段时间之后我最大的体会是技能框架的价值不在于让 AI 做更多事而在于让 AI 做的事更可预期。可预期意味着你可以放心地把重复任务交出去把精力留给真正需要判断力的工作。这个转变不会一夜发生但随着技能库的积累你会发现自己跟代理的协作越来越顺返工越来越少。最后分享一个小技巧每隔一段时间回顾一下你的技能库把那些超过一个月没用的技能归档。技能库不是越大越好保持精简才能让代理快速定位。我现在的技能库维持在十五个左右每个都经过多次迭代用起来很稳。