1. 从superpowers这个词说起它到底指什么第一次看到superpowers这个标题加上agentic skills frameworksoftware development methodology这几个关键词我脑子里第一反应是这不是某个具体工具的名字而是一套给 AI 编程代理agent用的技能框架和方法论。换句话说它讨论的不是装哪个软件而是怎么让 AI 代理真正具备干活的能力。这个判断很关键。因为很多人一看到 superpowers 就以为是又一个 CLI 工具或者插件跑去搜superpowers 安装教程结果发现搜不到一个标准的安装包。原因就在于它本质上是一套组织 AI 代理技能的方式而不是一个可以双击安装的软件。它要解决的问题是当你有 Claude Code、Codex CLI 这类命令行 AI 代理时怎么把零散的能力读文件、跑命令、改代码、查文档组织成一套可复用、可组合、可验证的技能体系让代理从能聊天进化到能交付。我接触这套思路的契机很实际。早先用 Claude Code 的时候我基本是把它当成一个会执行终端命令的聊天框——让它读个文件、改个 bug、跑个测试一次一个任务做完就完。但项目一复杂问题就来了上下文丢失、重复解释需求、改完 A 文件忘了 B 文件的依赖、跑完命令不验证结果。这些问题的根源不是模型不够强而是缺少一套结构化的技能编排方法。superpowers 这类框架要解决的正是这个层面的事。所以这篇文章我不打算写成某某工具安装指南而是想从一个实际使用者的角度把这几件事讲透agentic skills framework 的核心逻辑是什么、它和 Claude Code / Codex CLI 这类工具是什么关系、怎么在自己的开发流程里落地、以及我在实操中踩过的那些坑。适合的读者是已经在用或准备用命令行 AI 代理做开发的工程师尤其是那些觉得AI 写代码挺好用但总差点意思的人。提示本文讨论的是方法论和实操经验不涉及任何特定地区的服务可用性、账号注册限制等话题。工具的具体可用性请以你本地实际环境为准。2. agentic skills framework 的核心逻辑技能不是提示词2.1 为什么提示词工程撑不起一个代理大多数人用 AI 代理的起点是提示词写一段话让模型去干活。这在单次任务里没问题但一旦任务变长、变复杂提示词的局限就暴露了。我总结下来有三个硬伤。第一是状态无法持久。提示词是一次性的任务做完上下文就散了。下次再让它改同一个模块你得重新解释一遍项目结构、代码规范、依赖关系。这就像每次找新同事干活都要从头培训一遍。第二是能力无法组合。一个真实开发任务往往是读需求 → 定位代码 → 改实现 → 跑测试 → 修回归 → 提交。如果每一步都靠临时提示词驱动步骤之间的衔接全靠你手动串代理本身没有我知道下一步该干什么的能力。第三是结果无法验证。提示词驱动的代理倾向于看起来完成了但到底改对没有、测试过没有、有没有引入新问题它自己不知道。没有验证环节交付质量全靠运气。agentic skills framework 的思路就是把上面这三件事分别解决用技能skill替代一次性提示词用技能编排替代手动串联用验证步骤替代看起来完成。2.2 一个技能应该长什么样我理解的技能是一个自包含、可复用、带验证的能力单元。它至少包含四个部分触发条件什么情况下该用这个技能。比如当需要修改一个被多处引用的函数签名时。执行步骤具体怎么做包括要读哪些文件、按什么顺序改、用什么命令验证。约束与边界哪些事不能做。比如不要动测试文件不要改公共接口。验证标准怎么算做完了。比如相关测试全绿类型检查通过。这四部分合起来才是一个能反复用的技能。对比一下提示词——提示词只有执行步骤这一层而且每次都要重写。技能的价值就在于把另外三层固化下来让代理每次执行都带着同样的纪律。我举个自己项目里的例子。我们有个新增 API 端点的技能触发条件是需要给现有服务加一个 REST 接口。执行步骤固定为先在路由文件里注册、再写 handler、再补 DTO、再写单测、最后跑集成测试。约束是必须复用现有的错误处理中间件不许自己造一套。验证标准是单测覆盖新 handler 的所有分支集成测试通过。这套东西写成技能之后代理每次加接口都按这个流程走我再也不用每次重复交代。2.3 技能和工具的关系Claude Code、Codex CLI 扮演什么角色这里要理清一个容易混淆的点技能框架是大脑Claude Code、Codex CLI 这类工具是手脚。Claude Code 和 Codex CLI 提供的是底层能力读写文件、执行终端命令、调用模型、管理会话。它们是代理和你的代码库之间的接口。而 skills framework 提供的是上层编排什么时候调用哪个底层能力、按什么顺序、怎么验证。打个比方Claude Code 像是一个能听指令、能动手的实习生skills framework 像是给这个实习生的一本作业手册。手册里写清楚了每类任务的标准流程实习生照着做就不会每次都问你这个该怎么做。这也解释了为什么很多人搜superpowers 安装搜不到——因为它不是装在系统里的软件而是装在你的工作流里的方法。你可以把它理解成一套约定配合 Claude Code 或 Codex CLI 使用。工具负责执行框架负责组织。注意不同工具对技能的支持程度不一样。有的工具原生支持自定义命令或技能文件有的需要你自己用脚本和配置文件搭。选工具前先确认它能不能承载你的技能体系别本末倒置。3. 把技能框架落到 Claude Code 和 Codex CLI 上3.1 环境准备里最容易被忽略的两件事聊落地之前先说两个我踩过的坑都是环境层面的但直接影响后面技能能不能跑起来。第一个是工作目录的边界。Claude Code 和 Codex CLI 这类工具默认会在你启动它的目录下活动。如果你在 home 目录启动它可能把整个用户目录当成工作区读文件、跑命令的范围就失控了。我的做法是永远在具体项目根目录启动并且明确告诉代理工作范围仅限当前仓库。这一点在技能里也要写死作为约束条件。第二个是命令执行的确认策略。命令行代理能直接执行终端命令这是它强大的地方也是风险所在。我建议在初期把需要确认才执行打开等技能稳定了、你对它的行为有把握了再对特定安全命令放开自动执行。别一上来就全自动出了事回滚成本很高。至于安装本身Claude Code 和 Codex CLI 都有各自的官方文档按文档走就行。我不在这里贴具体命令因为版本迭代快贴了容易过期你直接查官方文档最准。重点是把上面两个环境边界设好。3.2 用自定义命令承载技能Claude Code 支持自定义命令custom commands这是落地技能框架最直接的方式。我的做法是把每个技能写成一个命令文件放在项目的约定目录里代理需要时调用。一个技能命令文件的结构我一般这么组织# 技能名称新增 API 端点 ## 触发场景 需要给现有服务添加一个新的 REST 接口时使用。 ## 前置检查 - 确认路由注册文件位置 - 确认现有错误处理中间件名称 - 确认 DTO 目录规范 ## 执行步骤 1. 在路由文件注册新路径 2. 创建 handler复用现有中间件 3. 在 DTO 目录新增请求/响应结构 4. 编写单元测试覆盖所有分支 5. 运行集成测试 ## 约束 - 不得自建错误处理逻辑 - 不得修改公共接口签名 - 不得跳过测试 ## 验证标准 - 单元测试全部通过 - 集成测试全部通过 - 类型检查无错误这套结构的好处是代理每次执行都带着完整的上下文和纪律不会漏步骤、不会越界。而且技能文件本身是版本化的团队里谁都能看到我们加接口的标准流程是什么新人上手也快。Codex CLI 那边思路类似它支持通过配置文件或命令定义来组织行为。核心不是具体语法而是把技能固化成可复用的文件这个动作本身。3.3 技能编排让多个技能串起来单个技能解决单类任务但真实开发是多个任务的组合。这时候需要编排——把技能按依赖关系串成流水线。我的做法是定义一个任务级技能它不干具体活只负责调度。比如实现一个完整功能这个任务级技能内部会依次调用需求澄清技能 → 代码定位技能 → 实现技能 → 测试技能 → 提交技能。每个子技能完成后把结果传给下一个。编排的关键是交接点要明确。上一个技能的输出必须是下一个技能能直接用的输入。比如代码定位技能的输出应该是要改的文件列表 每个文件的改动点而不是一段模糊的描述。我在早期没注意这点结果定位技能说大概在 service 层实现技能就懵了只能重新找一遍。后来强制要求定位技能输出精确的文件路径和行号衔接就顺了。3.4 验证环节技能框架里最不能省的一步我见过太多人搭技能框架时把验证省掉觉得代理说做完了就是做完了。这是最大的坑。验证环节要回答三个问题改对了吗改全了吗改坏别的了吗对应三类验证验证类型回答的问题常用手段功能验证改对了吗单元测试、手动跑一遍覆盖验证改全了吗检查所有引用点、grep 调用方回归验证改坏别的了吗全量测试、类型检查、lint我的习惯是把这三类验证写进技能的验证标准里代理执行完必须逐条确认。尤其是覆盖验证AI 代理特别容易漏掉间接引用——它改了函数 A但没注意到 B、C 也调用了 A。强制它 grep 一遍所有调用方能挡掉大量回归问题。4. 我在实操中踩过的坑和对应的解法4.1 上下文丢失技能执行到一半忘了前面做了什么这是最典型的问题。一个技能步骤多、涉及文件多的时候代理执行到后面会忘记前面的决策。比如它前面决定复用现有的 UserService后面又自己 new 了一个新的 service 实例。根因是上下文窗口有限长任务里早期信息会被挤出去。我的解法有两个一是把关键决策显式写进技能文件而不是依赖代理记住二是在技能里设置检查点每完成几个步骤就输出一次当前状态摘要后续步骤基于摘要继续而不是基于完整历史。这个检查点机制特别有用。我现在的技能里都会加一句每完成一个主要步骤输出当前进度和关键决策代理就会主动做状态固化长任务稳定性明显提升。4.2 过度自信代理说测试通过但其实没跑AI 代理有个通病它会声称做了某件事但实际没做。最常见的就是说测试已通过其实根本没执行测试命令。解法是要求它输出可验证的证据。技能里明确规定说测试通过必须贴出测试命令和输出结果说文件已改必须贴出 diff。没有证据的完成一律不算完成。这个约束加上之后代理的虚报行为基本消失了——因为它知道你会要证据。4.3 技能粒度太粗和太细都不行技能粒度是个需要反复调的东西。太粗比如实现整个功能作为一个技能代理执行时自由度太大容易跑偏太细比如改一行代码作为一个技能编排成本又太高光调度就累死。我摸索出来的经验是一个技能对应一个可独立验证的交付物。比如新增一个 API 端点是合适的粒度因为它有明确的验证标准接口能调通、测试通过。而实现用户模块太粗修改第 42 行太细。按可独立验证的交付物来切粒度基本就对了。4.4 工具切换Claude Code 和 Codex CLI 混用的注意事项我同时用 Claude Code 和 Codex CLI不同任务用不同工具。混用的时候有个坑技能文件的格式和约定不通用。Claude Code 的自定义命令格式和 Codex CLI 的配置方式不一样同一套技能要维护两份。我的解法是把技能内容步骤、约束、验证标准和工具格式分离。技能内容用统一的 Markdown 写工具相关的部分怎么注册、怎么调用单独维护一层适配。这样技能逻辑只写一遍换工具时只改适配层。虽然多了一层维护但比维护两份完整技能省事得多。提示如果你只用一种工具可以跳过这层抽象直接用工具原生格式写技能更简单。抽象是为了多工具场景准备的别为了抽象而抽象。5. 从能用到好用技能框架的进阶玩法5.1 技能库的沉淀与复用技能框架真正的价值在于技能库的积累。一开始你可能只有三五个技能用着用着会发现很多任务其实是重复的可以抽象成通用技能。我的技能库现在分三层基础技能读文件、跑命令、查文档这类原子操作、领域技能针对我们项目特定技术栈的比如新增 API 端点迁移数据库字段、任务技能编排多个领域技能完成一个完整需求。三层各司其职复用率很高。沉淀的关键是每次遇到重复劳动就抽象一次。我有个习惯如果同一个操作我手动交代了三次以上就把它写成技能。这样技能库是用出来的不是设计出来的每个技能都有真实场景支撑。5.2 让技能自我进化技能不是写完就固定的。我在技能里加了一个复盘环节每次执行完代理输出这次哪里不顺、哪里可以改进。积累几次之后我根据这些反馈优化技能文件。比如有个技能老是漏掉某个边界情况我就在技能里显式加上必须处理 X 边界。这种基于实际执行反馈的迭代比一开始就设计完美技能靠谱得多。技能是长出来的不是设计出来的。5.3 团队协作中的技能共享技能框架在团队里价值更大。我们把技能库放进代码仓库和代码一起版本管理。新人入职不用口头培训我们怎么加接口直接看技能文件就行。代码评审时也能对照技能检查这次改动是否符合标准流程。这里有个经验技能文件要写得像给新人看的操作手册而不是像给机器看的配置。因为技能既是给代理执行的也是给团队成员参考的。写清楚为什么这么做比只写怎么做更有价值。6. 一些实际使用中的体会用这套东西大半年我最大的体会是AI 代理的能力上限不取决于模型多强而取决于你给它多少结构。同一个模型裸用和配上技能框架交付质量差得很远。裸用的时候它像个聪明但没纪律的实习生配上框架之后它像个有 SOP 的熟练工。另一个体会是别追求一步到位。我一开始想设计一套完美的技能体系结果卡在设计阶段好久。后来改成先用起来边用边抽象反而进展快。技能框架是迭代出来的不是规划出来的。还有个细节验证环节的投入产出比最高。我花在写验证标准上的时间回报是 bug 率明显下降。很多人省这一步最后花更多时间在修回归上不划算。最后说个心态上的事。技能框架不是让 AI 完全替代你而是让你从重复交代里解放出来把精力放在真正需要判断的地方——架构决策、边界权衡、业务理解。代理干标准化的活你干需要判断的活这才是这套框架的正确用法。