1. 从“superpowers”说起一个让 AI 编程助手真正长出“技能树”的框架第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“这玩意儿终于把 agentic skills framework 这件事讲明白了”。点进去看完之后我的第一反应是这东西解决了一个我憋了很久的痛点——我们手里的 AI 编程助手比如 Claude Code、Codex CLI能力其实很强但它们缺少一套可复用、可组合、可沉淀的“技能体系”。打个比方。你招了一个天赋极高的新人程序员他脑子快、代码写得漂亮但每次遇到“部署一个带数据库的全栈应用”这种活儿他都要从零开始问你用什么框架、目录怎么分、环境变量放哪、迁移脚本怎么写。他每次都能做对但每次都要重新想一遍。superpowers 想干的事就是把这些“每次都要重新想一遍”的东西变成一套结构化的技能skills让 AI 助手在需要的时候自动调用而不是每次都靠临场发挥。所以这篇文章我想聊的不是“superpowers 是什么”这种百科式介绍而是作为一个天天跟 Claude Code、Codex CLI 打交道的人我怎么理解这套 agentic skills framework它背后的 software development methodology 到底在解决什么问题以及如果你想上手具体该怎么引入这些技能、怎么和 Claude Code / Codex CLI 配合、中间会踩哪些坑。适合谁看三类人一是已经在用 Claude Code 或 Codex CLI但感觉“每次都像重新开一局”的开发者二是想给自己的团队沉淀一套 AI 辅助开发规范的技术负责人三是纯粹对 agentic skills framework 这个概念好奇、想搞清楚它和普通 prompt 模板有什么区别的人。不管你是刚装完 Claude Code 的新手还是已经能熟练敲/compact、/model、/resume的老用户下面这些内容应该都能对上你的某个具体困惑。2. superpowers 到底在解决什么问题从“提示词堆砌”到“技能工程”2.1 为什么普通 prompt 模板撑不起一个完整项目先说一个我自己的真实经历。去年我尝试用 Claude Code 做一个内部工具前后写了大概三十多个 prompt 模板存在一个 markdown 文件里每次开工就复制粘贴。刚开始挺爽但项目做到第二周就崩了——不是代码崩了是我的模板体系崩了。问题出在哪普通 prompt 模板是“扁平”的。它假设你面对的任务是孤立的写一个函数、改一个 bug、加一个接口。但真实项目是“立体”的你要先理解现有代码结构再决定改哪里改完要跑测试测试挂了要定位定位完要更新文档文档更新完还要考虑部署。这一连串动作之间是有依赖、有状态、有上下文的。扁平模板没法表达这种依赖关系于是你只能靠人脑去记“现在该用哪个模板了”一旦项目复杂起来人脑就成了瓶颈。superpowers 这类 agentic skills framework 的核心洞察就在这里AI 助手缺的不是单点能力而是把能力组织起来的结构。它把“技能”定义成一个有输入、有输出、有前置条件、有触发场景的单元然后让这些单元可以像积木一样组合。这跟软件工程里从“脚本”进化到“模块”再到“框架”的路径是一模一样的。2.2 技能skills和工具tools的本质区别很多人第一次接触 superpowers 会把它和 Claude Code 自带的工具系统搞混。Claude Code 本身有一堆工具读文件、写文件、执行终端命令、搜索代码。这些是“工具”它们回答的是“我能做什么动作”。而 superpowers 里的“技能”回答的是“在什么情况下、按什么顺序、用什么标准去做这些动作”。举个具体例子。Claude Code 有“执行终端命令”这个工具但“初始化一个 Python 项目并配置好虚拟环境、依赖管理、测试框架”是一个技能。前者是原子操作后者是一套编排好的操作序列里面还嵌着判断逻辑如果检测到已有pyproject.toml就跳过初始化如果检测到用的是 poetry 就换一套命令。这种“带判断的编排”才是技能的价值所在。我自己的理解是工具是动词技能是动词加副词加条件从句。工具是“写”技能是“在确认文件不存在的前提下用追加模式写并且写完立刻校验语法”。这个区别听起来细微但在实际项目里它决定了 AI 是“能干活”还是“干得靠谱”。2.3 为什么这套方法论现在才火起来agentic skills framework 这个概念其实不新但为什么最近才在 Claude Code、Codex CLI 这个圈子里火起来我觉得有三个条件同时成熟了。第一是模型能力到位了。技能框架要求 AI 能理解“前置条件”“触发场景”这种抽象概念还要能在执行过程中做判断。早两年的模型做这个会频繁出错现在 Claude 系列和 GPT 系列在这方面的稳定性已经够用了。第二是CLI 形态的编程助手普及了。Claude Code、Codex CLI 这种直接在终端里跑、能读写文件、能执行命令的形态天然适合承载技能框架。因为技能最终要落地成“对文件系统和终端的一系列操作”CLI 助手正好有这个权限。第三是开发者被 prompt 管理折磨够了。当你的 prompt 库超过二十个维护成本就指数上升。大家开始意识到与其管理一堆散装 prompt不如管理一套有结构的技能库。这个需求是真实存在的不是造出来的。3. 拆解 superpowers 的核心结构一个技能到底长什么样3.1 技能的四个核心要素我翻了不少关于 superpowers 的讨论也自己动手拆过几个技能定义总结下来一个完整的技能通常包含四个要素。这四个要素缺一个技能就会变得“不好用”或者“容易被误触发”。触发条件Trigger什么情况下该用这个技能。这个必须写得足够具体不能是“当用户需要帮助时”这种废话。好的触发条件长这样“当用户要求创建一个新的 REST API 端点且项目中已存在至少一个同类端点时”。具体到这种程度AI 才能准确判断。前置检查Preconditions执行前必须确认的事情。比如“确认项目根目录存在package.json”“确认当前分支不是 main”。这一步是防止技能在错误的环境下执行造成破坏。执行步骤Steps具体的操作序列。这里的关键是每一步都要有明确的“完成标志”不能是“修改相关文件”这种模糊描述而应该是“在src/routes/下创建{name}.route.ts导出名为{name}Router的对象”。验证与回滚Verification Rollback执行完怎么确认成功失败了怎么恢复。这一步最容易被忽略但恰恰是区分“玩具技能”和“生产级技能”的分水岭。3.2 技能之间的依赖与组合关系单个技能再强也只是个工具。superpowers 真正有意思的地方是技能之间可以组合。我见过一个比较典型的设计一个“创建数据模型”的技能会自动触发“生成迁移脚本”技能后者又会触发“更新 API 文档”技能。这种链式触发不是硬编码的而是通过技能定义里的“后置动作”声明的。这里有个设计上的取舍值得说。你可以选择让技能“自动链式触发”也可以选择“只提示不自动执行”。我个人的经验是涉及文件创建和修改的自动触发没问题涉及删除、覆盖、部署的一定要人工确认。这个边界如果划不清楚技能框架就会从“提效工具”变成“事故制造机”。3.3 一个技能定义的实际样子下面是我根据常见实践整理的一个技能定义示例用 YAML 风格写因为这种格式在 Claude Code 和 Codex CLI 的配置里都比较常见。注意这不是官方标准而是我见过的几种写法里比较清晰的一种。name: create-rest-endpoint description: 在现有 Express 项目中创建一个新的 REST API 端点 trigger: - user_intent: 创建新的 API 端点 - project_has: package.json 中包含 express 依赖 - project_has: src/routes/ 目录存在 preconditions: - check: git status --porcelain expect: empty message: 工作区有未提交改动请先提交或暂存 - check: test -d src/routes expect: true steps: - action: read_file path: src/routes/index.ts purpose: 了解现有路由注册方式 - action: create_file path: src/routes/{{name}}.route.ts template: route-template.ts - action: modify_file path: src/routes/index.ts operation: append_import_and_register verification: - action: run_command command: npm run build expect_exit_code: 0 - action: run_command command: npm test -- --grep {{name}} expect_exit_code: 0 rollback: - action: delete_file path: src/routes/{{name}}.route.ts - action: git_checkout path: src/routes/index.ts这个定义里{{name}}是变量由触发时的上下文填充。route-template.ts是一个模板文件技能执行时会读取它并替换变量。这种“模板加变量”的方式比让 AI 每次现写代码要稳定得多因为模板是你审过的AI 只负责填变量。提示技能定义里的preconditions不要写太多。我见过有人写了十几条前置检查结果技能触发率极低因为总有一条不满足。我的经验是控制在三条以内只检查那些“不满足就会出大事”的条件。4. 在 Claude Code 和 Codex CLI 里引入 superpowers 的完整实操4.1 环境准备先把 Claude Code 或 Codex CLI 跑起来不管你用哪套技能框架前提是你得有一个能跑的 AI 编程助手。Claude Code 和 Codex CLI 是目前最主流的两个选择安装方式我分别说一下因为热词里问这个的人特别多。Claude Code 的安装官方推荐的方式是通过 npm 全局安装。在 macOS 或 Ubuntu 上命令是npm install -g anthropic-ai/claude-code装完之后在终端输入claude就能启动。Windows 用户要注意Claude Code 对 Windows 的原生支持一直有点磕磕绊绊热词里那条“由于与64位版本的windows不兼容”就是典型症状。我的建议是 Windows 用户优先考虑 WSL2在 WSL 里按 Ubuntu 的方式装稳定性会好很多。如果你非要在原生 Windows 上用记得确认 Node.js 版本在 18 以上并且用管理员权限装。Codex CLI 的安装类似也是 npm 包npm install -g openai/codex装完输入codex启动。Codex CLI 的命令体系和 Claude Code 不太一样Claude Code 里常用的/compact、/model、/resume这些斜杠命令在 Codex CLI 里对应的是不同的交互方式。这个后面会细说。至于 VS Code 集成Claude Code 有官方插件在扩展市场搜 “Claude Code” 就能找到。装完之后在 VS Code 的设置里配置一下 API key 或者登录账号就能在编辑器里直接调用。这里有个坑VS Code 插件和终端版是两套独立的配置你在终端里登录了插件里不一定同步。我见过有人终端能用、插件报“your organization has disabled claude subscription access”折腾半天才发现是插件里没重新登录。4.2 把技能库接入 Claude Code 的三种方式技能库准备好之后怎么让 Claude Code 用上我试过三种方式各有适用场景。第一种是项目级配置。在项目根目录建一个.claude/skills/目录把技能定义文件放进去。Claude Code 启动时会自动扫描这个目录。这种方式的好处是技能跟着项目走团队里每个人拉下代码就有一致的技能库。缺点是每个项目都要配一遍公共技能不好复用。第二种是用户级配置。在用户主目录下的.claude/skills/放技能这样所有项目都能用。适合放那些通用的、跟具体项目无关的技能比如“生成 commit message”“解释这段代码”。缺点是项目特有的技能混进来会显得乱。第三种是通过 MCP 服务。如果你有一套集中管理的技能库可以把它包装成一个 MCP 服务Claude Code 通过 MCP 协议去调用。这种方式最灵活但配置也最复杂适合团队规模比较大、需要统一管理技能版本的场景。我自己的做法是混合用户级放通用技能项目级放项目特有技能两边不冲突。Claude Code 会同时加载两个目录同名技能以项目级为准。4.3 技能触发时机的调试技巧技能装好了但“不触发”或者“乱触发”是最常见的问题。我踩过的坑里八成都是触发条件写得太模糊。调试触发时机我有个笨但有效的办法在技能定义里加一条日志动作。比如在steps最前面加一个“输出当前触发原因”的动作这样每次技能被调用你都能在终端里看到它是被哪条规则触发的。跑一段时间你就能看出哪些触发条件太宽、哪些太窄。还有一个技巧是用/compact前后的行为对比来验证。Claude Code 的/compact会压缩上下文如果压缩之后技能还能正常触发说明触发条件不依赖具体的对话历史是“健壮”的如果压缩之后就失灵了说明触发条件里隐含了太多上下文信息需要改成更显式的判断。Codex CLI 这边触发机制和 Claude Code 略有不同它更依赖显式的命令调用而不是自动识别意图。所以在 Codex CLI 里技能往往需要你手动指定比如codex run create-rest-endpoint --nameusers。这种方式的优点是可控缺点是不够“智能”。两种风格没有绝对优劣看你更看重可控性还是流畅度。4.4 用 cc switch 接入第三方模型的注意事项热词里提到 “使用 cc switch 接入 deepseek v4、qwen、glm 等模型”这个我单独说一下因为涉及技能框架能不能跨模型工作的问题。cc switch 这类工具的作用是让 Claude Code 的界面去调用非 Claude 的模型。技术上可行但有个关键点要注意技能框架的触发逻辑很大程度上依赖模型对指令的理解能力。Claude 系列在理解“前置条件”“触发场景”这类结构化指令上表现比较稳换成其他模型之后同样的技能定义可能会触发不准。我的建议是如果你要用第三方模型跑技能框架先把技能定义里的自然语言描述改得更“直白”一些减少需要模型“意会”的部分。另外第三方模型的上下文窗口和 Claude 不一样/compact的时机也要相应调整。这些细节不调体验会差很多。5. 技能库的日常维护从“能用”到“好用”的关键动作5.1 技能版本管理别让技能库变成垃圾场技能库最大的敌人不是写不出来而是越写越乱。我见过一个团队半年攒了两百多个技能结果没人知道哪个是当前有效的新人进来完全不敢用。解决这个问题的核心是版本管理。我的做法是给每个技能加一个version字段并且在技能描述里写清楚“这个版本改了什么”。更重要的是定期做技能审计每个月花半小时把过去一个月没被触发过的技能过一遍要么删掉要么合并要么更新触发条件。技能库不是越多越好是越准越好。还有一个实践是给技能打标签比如#frontend、#database、#deploy。这样在技能多起来之后你可以按标签批量启用或禁用。比如做前端任务时把#deploy标签的技能全禁掉避免误触发。5.2 技能冲突的处理当两个技能都想干活技能冲突是必然会发生的。比如你有一个“自动格式化代码”的技能还有一个“生成代码”的技能后者生成的代码格式可能不符合前者的规范两个技能就会打架。处理冲突的原则是明确优先级。在技能定义里加一个priority字段数字越小优先级越高。当两个技能同时满足触发条件时高优先级的先执行执行完之后重新评估低优先级的技能是否还需要执行。这个机制听起来简单但能解决大部分冲突。另一种冲突是“互斥”的比如“使用 tabs 缩进”和“使用 spaces 缩进”两个技能。这种要在定义里显式声明conflicts_with让框架知道这两个不能同时启用。我建议在技能库规模超过五十个之后一定要做一次冲突梳理把互斥关系标清楚。5.3 技能效果的量化评估技能好不好用不能靠感觉得有数据。我自己的做法是记录三个指标触发次数、成功率、平均执行时长。触发次数告诉你这个技能是不是真的被需要。如果一个技能三个月没触发过要么是触发条件写错了要么是这个需求根本不存在。成功率是执行成功验证步骤通过的比例。低于 80% 的技能要重点排查通常是前置检查不够或者步骤里有模糊描述。平均执行时长则关系到体验。一个技能如果每次要跑五分钟那它再准也会让人烦躁。这时候要考虑把技能拆细或者把耗时的验证步骤改成异步的。这三个指标不需要多复杂的工具在技能定义里加个日志输出定期 grep 一下就能统计。关键是养成习惯别让技能库“野蛮生长”。6. 常见问题与排查技巧实录6.1 技能不触发怎么办这是最高频的问题。排查顺序我一般是这样的先确认技能文件放对位置了。Claude Code 的项目级技能在.claude/skills/用户级在~/.claude/skills/放错了不会报错就是静默不加载。这个坑我踩过找了半天才发现是目录名少了个点。再确认文件格式对。YAML 对缩进极其敏感一个 tab 和两个空格的混用就能让整个文件解析失败。建议用支持 YAML 校验的编辑器写完先校验一遍。然后看触发条件是不是太严。把trigger里的条件逐条拿出来手动验证当前环境是否满足。我见过有人写了“项目使用 TypeScript 且 tsconfig 中 strict 为 true”结果项目虽然是 TS 但 strict 是 false技能就永远不触发。最后看模型有没有理解。有些触发条件写得太“文学”模型理解不了。比如“当用户显得很着急时”这种模型没法判断。改成“当用户消息中包含‘紧急’‘尽快’等词时”就靠谱多了。6.2 技能执行到一半失败怎么恢复技能执行失败不可怕可怕的是失败之后环境处于“半完成”状态既不是执行前也不是执行后。这时候回滚机制就关键了。我的经验是任何会修改文件系统的技能都必须有回滚步骤。回滚步骤要写得和执行步骤一样具体不能是“恢复原状”这种废话。对于创建文件回滚就是删除对于修改文件回滚就是用 git checkout 或者从备份恢复对于执行命令回滚往往做不到所以这类技能的前置检查要格外严格。还有一个技巧是在技能执行前自动打一个 git stash 或者创建一个临时分支。这样无论技能怎么折腾最坏情况就是git checkout .一把梭。这个动作可以做成框架级的通用逻辑不用每个技能单独写。6.3 技能和手动操作的边界在哪用久了技能框架容易产生一种“什么都想做成技能”的冲动。我的建议是只把重复三次以上的操作做成技能。做一次两次的手动干就行做成技能反而增加维护成本。另外涉及“判断”的操作如果判断逻辑经常变也不适合做成技能。比如“这段代码该不该重构”这种判断每次都不一样做成技能只会束缚手脚。技能适合的是那些“流程固定、判断标准明确”的操作。6.4 常见问题速查表问题现象可能原因排查动作解决方式技能完全不触发文件位置错误检查.claude/skills/目录移动到正确目录技能偶尔触发触发条件依赖上下文用/compact后测试改成显式条件判断执行报语法错误YAML 缩进问题用校验工具检查统一用空格缩进执行到一半卡住前置检查未通过查看日志输出放宽或修正前置条件多个技能打架优先级未定义检查priority字段显式声明优先级和互斥第三方模型下失灵模型理解能力差异换回 Claude 对比简化技能描述语言回滚不干净回滚步骤太模糊检查rollback定义写成具体文件操作注意技能库的调试是个“慢工出细活”的事。我见过太多人一开始热情满满写了五十个技能结果因为几个触发问题没解决最后整个库都弃用了。建议从三五个核心技能开始跑顺了再慢慢加。7. 我对这套方法论的真实看法用 superpowers 这类 agentic skills framework 大半年下来我最大的体会是它改变的不是 AI 的能力上限而是 AI 的稳定性下限。以前用 Claude Code好的时候惊为天人差的时候气得想砸键盘。现在有了技能框架虽然偶尔还是会有惊喜和惊吓但大部分时候它就在一个“靠谱”的区间里稳定输出。这种稳定性对于真正拿它干活的人来说比偶尔的惊艳重要得多。另一个体会是技能框架逼着我把很多“只可意会”的开发经验写成了“可以言传”的规则。这个过程本身就有价值。写技能定义的时候你会被迫想清楚这个操作的边界条件是什么、失败模式有哪些、怎么验证成功。这些思考就算不用 AI对写代码本身也是有好处的。最后分享一个我最近在试的扩展方向把技能框架和项目的 CI 流程打通。让技能在本地执行完之后自动触发一次轻量的 CI 检查检查通过才算技能执行成功。这样技能的成功率统计就更准了也能防止一些“本地能跑、推上去就挂”的问题。这个还在摸索阶段等跑顺了再单独写一篇。