1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。我当时的第一反应是又是一个造概念的项目。但点进去看了半小时之后我改主意了——它确实在试图解决一个真实存在的痛点。这个痛点是什么简单说就是你手里有 Claude Code、有 Codex CLI甚至可能还配了本地模型但你不知道怎么让它们真正“干活”。大多数人用这些工具的方式还停留在“我问一句、它答一句”的聊天模式。你让它写个函数它写了你让它改个 bug它改了。但如果你说“帮我把这个项目的测试覆盖率从 60% 提到 85%顺便把 CI 流程也优化一下”它大概率会给你一段看起来很有道理但根本跑不通的建议。superpowers 这个项目的核心主张就是把软件开发方法论拆解成 agent 可以理解和执行的“技能单元”然后通过一套框架把这些技能编排起来。它不是一个工具而是一套方法论 框架的组合。你可以把它理解成给 AI 编程助手写的“操作手册”——告诉它在什么场景下该调用什么能力、按什么顺序执行、遇到什么情况该停下来问人。为什么这件事重要因为现在的 AI 编程工具已经足够聪明了但它们缺的是“纪律性”。一个人类高级工程师在接到任务时会先理解需求、再拆解步骤、然后逐步执行、最后验证结果。而 AI 助手往往是一口气给你一大段代码你也不知道它中间有没有跳步、有没有遗漏边界条件。superpowers 试图填补的就是这个 gap。这套框架适合谁来参考我梳理了一下大概有三类人第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师想把自己的工作流标准化第二类是在团队里负责搭建 AI 辅助开发流程的技术负责人需要一套可复用的方法论第三类是对 agentic skills 这个概念感兴趣、想自己动手搭一套类似系统的开发者。如果你属于这三类中的任何一类下面的内容应该都能给你一些可以直接抄作业的东西。2. 核心设计思路拆解为什么是“技能框架”而不是“提示词集合”2.1 从提示词工程到技能编排的范式转变过去两年大家聊 AI 编程助手聊的都是“提示词怎么写”。你去看那些热词什么“claude code使用教程”、“codex cli 命令哪些 /compact /model /resume”本质上都是在问“我怎么跟它说话它才能听懂”。但 superpowers 的思路不太一样它认为问题不在于你怎么说而在于你有没有一套结构化的技能定义。打个比方提示词工程就像是你在跟一个聪明但没受过专业训练的实习生说话你得把每件事都解释得很清楚。而技能框架就像是给这个实习生发了一本《员工手册》里面写清楚了“遇到代码审查该怎么做”、“遇到性能问题该按什么流程排查”、“遇到需求变更该走什么审批流”。实习生不需要你每次都说一遍他照着手册执行就行。这个转变的关键在于技能是可组合的、可复用的、可验证的。一个“代码审查”技能可以被“提交 PR”技能调用也可以被“重构”技能调用。而提示词是一次性的你这次写了一段很长的 prompt 让 AI 做代码审查下次换个场景又得重新写。2.2 技能单元的粒度设计为什么不能太粗也不能太细superpowers 在技能粒度上的设计思路很值得琢磨。我看了它的文档结构之后发现它把技能分成了三个层级原子技能最小的可执行单元比如“读取文件”、“运行测试”、“解析错误日志”。这些技能不依赖其他技能输入输出都很明确。复合技能由多个原子技能组合而成比如“修复一个 bug”可能包含“读取错误日志 → 定位相关代码 → 生成修复方案 → 运行测试验证”这一串原子技能。工作流技能面向完整场景的技能编排比如“实现一个新功能”可能包含“理解需求 → 拆解任务 → 逐个实现 → 集成测试 → 代码审查”这一整套流程。为什么这么分因为不同场景需要不同粒度的控制。如果你只是想让 AI 帮你改个 typo调用原子技能就够了没必要走完整工作流。但如果你要让它独立完成一个模块的开发就需要工作流技能来保证它不会跳步。注意粒度设计是这套框架里最容易踩坑的地方。我见过有人把所有东西都塞进一个“超级技能”里结果就是 AI 执行到一半就迷路了因为它不知道当前进行到哪一步、下一步该干什么。技能粒度太粗AI 的上下文窗口扛不住粒度太细编排逻辑又会变得极其复杂。2.3 与 Claude Code、Codex CLI 的集成逻辑superpowers 本身不是一个独立的 AI 编程工具它更像是一层“方法论中间件”。你可以把它和 Claude Code 配合使用也可以和 Codex CLI 配合使用。集成的核心思路是把技能定义转换成对应工具能理解的指令格式。比如在 Claude Code 里你可以通过自定义指令或者项目配置文件来注入技能定义。在 Codex CLI 里你可以通过命令别名或者脚本封装来实现类似的效果。关键是superpowers 提供了一套标准的技能描述格式你只需要写一次技能定义就可以在不同的工具之间迁移。这解决了一个很实际的问题现在很多人同时在用 Claude Code 和 Codex CLI甚至还在 VS Code 里配了插件。如果没有统一的技能定义你每换一个工具就得重新调教一遍。superpowers 的思路是“技能定义与工具解耦”你定义的是“做什么”而不是“怎么跟某个特定工具说”。3. 核心细节解析与实操要点技能定义、编排与执行3.1 技能定义的结构一个技能应该包含哪些字段我参考了 superpowers 的文档结构和几个开源实现总结出一个技能定义至少应该包含以下字段字段名作用是否必填name技能名称唯一标识是description技能描述说明这个技能做什么是inputs输入参数定义包括类型和约束是outputs输出结果定义包括格式和验证规则是steps执行步骤可以是原子操作或子技能调用是preconditions前置条件不满足则不能执行否postconditions后置条件执行完必须满足否error_handling错误处理策略否examples使用示例否这个结构看起来简单但每个字段的设计都有讲究。比如preconditions和postconditions很多人会忽略但它们其实是保证技能可靠性的关键。举个例子一个“运行测试”技能的前置条件可能是“项目已经编译通过”后置条件可能是“测试报告已生成且退出码为 0”。如果没有这两个条件AI 可能会在项目还没编译的时候就跑去跑测试然后给你一堆莫名其妙的错误。error_handling字段也很重要。AI 执行技能时遇到错误是常态关键是要定义清楚“遇到什么错误该重试、什么错误该跳过、什么错误该停下来问人”。我见过太多人写的技能定义里完全没有错误处理结果就是 AI 遇到一个网络超时就卡在那里反复重试浪费了大量 token。3.2 技能编排的三种模式串行、并行与条件分支技能编排是 superpowers 框架里最核心的部分。根据我的实践经验常用的编排模式有三种串行编排是最简单的就是按顺序执行技能。比如“读取需求文档 → 生成代码 → 运行测试 → 提交代码”。这种模式适合步骤之间有严格依赖关系的场景。并行编排适合那些互不依赖的技能。比如你可以同时让 AI 去“检查代码风格”和“运行安全扫描”两个技能的结果最后汇总。这种模式能显著缩短执行时间但要注意资源竞争问题——如果两个技能都要写同一个文件就会出问题。条件分支是最复杂的但也是最实用的。比如“如果测试失败则执行调试技能如果测试通过则执行代码审查技能”。这种模式让 AI 能够根据实际情况动态调整执行路径而不是死板地走完所有步骤。实操心得我建议新手先从串行编排开始把一条完整的流程跑通之后再逐步引入并行和条件分支。一上来就搞复杂编排很容易因为某个环节的边界条件没处理好导致整个流程崩溃。3.3 技能执行的上下文管理如何避免“失忆”AI 在执行多步技能时最大的敌人是“上下文丢失”。你让它先读一个文件再改另一个文件它可能改着改着就忘了第一个文件里有什么。superpowers 在这方面提供了一些思路显式状态传递每个技能的输出都作为下一个技能的输入显式传递而不是依赖 AI 的“记忆”。检查点机制在关键步骤之后保存当前状态如果后续步骤失败可以从检查点恢复而不是从头开始。上下文摘要当上下文太长时自动生成摘要只保留关键信息。这些机制听起来很工程化但实际用起来效果很明显。我之前用 Claude Code 做一个重构任务涉及十几个文件如果没有检查点机制中间一旦出错就得从头再来非常浪费时间。4. 实操过程与核心环节实现从零搭建一套技能框架4.1 环境准备Claude Code 与 Codex CLI 的安装配置在开始搭建技能框架之前你需要先把基础工具装好。这里我分别说一下 Claude Code 和 Codex CLI 的安装要点。Claude Code 的安装根据你的操作系统不同步骤略有差异。在 macOS 上通常是通过包管理器安装在 Ubuntu 上需要先确认 Node.js 版本符合要求然后通过 npm 全局安装。安装完成之后你需要配置 API 密钥或者登录账号。这里有个常见问题有些人在 VS Code 里配置 Claude Code 插件时会遇到“your organization has disabled claude subscription access”的提示这通常是因为组织管理员限制了访问权限需要联系管理员开通。Codex CLI 的安装相对简单一些但要注意命令的版本兼容性。安装完成之后你可以通过/compact、/model、/resume等命令来管理会话。如果你需要删除 Codex CLI 的某个指令可以通过修改配置文件或者使用命令行参数来覆盖。注意如果你在 Windows 上安装可能会遇到“由于与64位版本的 Windows 不兼容”的提示。这种情况下建议使用 WSL2 环境或者直接换用 macOS/Linux 系统。我在 Windows 上折腾了半天最后还是切到了 Ubuntu省心很多。4.2 技能定义文件的编写一个完整的示例下面是一个“运行测试并生成报告”的技能定义示例你可以直接参考这个结构来写自己的技能name: run-tests-and-report description: 运行项目测试套件并生成结构化报告 inputs: - name: test_command type: string default: npm test description: 测试命令 - name: timeout type: integer default: 300 description: 超时时间秒 outputs: - name: test_report type: object properties: total: integer passed: integer failed: integer failures: array preconditions: - 项目依赖已安装 - 测试命令可执行 steps: - action: execute_command command: {{test_command}} timeout: {{timeout}} capture_output: true - action: parse_test_output input: {{previous_output}} format: jest - action: generate_report input: {{parsed_result}} output_format: markdown postconditions: - 测试报告已生成 - 失败用例已列出 error_handling: - condition: command_not_found action: report_error_and_stop - condition: timeout action: retry_once_then_stop这个定义里steps部分就是技能的执行逻辑。你可以看到每一步都明确了输入和输出这样 AI 在执行时就不会“自由发挥”。error_handling部分定义了两种错误情况的处理策略避免 AI 在遇到问题时不知所措。4.3 技能编排脚本的编写把多个技能串起来有了单个技能的定义之后下一步就是编排。下面是一个简单的编排脚本示例实现了“代码提交前检查”的流程from superpowers import Skill, Workflow # 定义技能 lint_skill Skill.load(lint-code) test_skill Skill.load(run-tests-and-report) review_skill Skill.load(code-review) # 定义工作流 workflow Workflow(namepre-commit-check) # 串行执行先 lint再测试最后审查 workflow.add_step(lint_skill, on_failurestop) workflow.add_step(test_skill, on_failurestop) workflow.add_step(review_skill, on_failurewarn) # 条件分支如果 lint 失败跳过测试直接报告 workflow.add_condition( if_skilllint_skill, conditionfailed, then_actionskip_to_end ) # 执行 result workflow.execute(context{project_path: ./my-project}) print(result.summary)这个编排脚本的逻辑很清晰先跑 lint如果 lint 失败就直接结束并报告如果 lint 通过就跑测试测试通过后再做代码审查。代码审查失败不会阻断流程只是给出警告。4.4 与本地模型的集成调用 LM Studio 的实践如果你不想用云端 API想用本地模型superpowers 也可以和 LM Studio 配合。核心思路是把 LM Studio 的本地 API 地址配置到 Claude Code 或 Codex CLI 的模型设置里。具体操作是在 LM Studio 里启动本地服务记下 API 地址通常是http://localhost:1234/v1然后在 Claude Code 的配置文件里把模型端点指向这个地址。这样你就可以用本地模型来执行技能了。不过要注意本地模型的上下文窗口通常比云端模型小所以在设计技能时要控制单次输入的长度。我的经验是如果本地模型的上下文是 8K那单个技能的输入最好控制在 4K 以内留一半给输出。5. 常见问题与排查技巧实录5.1 技能执行失败的典型原因与排查路径在实际使用中技能执行失败的原因五花八门。我整理了一个速查表覆盖了最常见的几种情况现象可能原因排查方法解决方案技能卡在第一步不动前置条件不满足检查 preconditions 定义补充前置检查或调整条件输出格式不符合预期输出解析规则有误查看原始输出与解析结果对比调整解析规则或增加格式约束执行到一半突然停止上下文超限检查 token 使用量拆分技能或增加摘要机制反复重试同一个步骤错误处理策略不当查看 error_handling 配置增加重试上限或改为人工介入技能之间数据传递丢失状态传递未显式定义检查 inputs/outputs 映射显式定义数据传递路径这个表里的每一条都是我实际踩过的坑。特别是“上下文超限”这一条很多人会忽略。AI 在执行多步技能时上下文是累积的如果不做控制跑到第五步可能就超了。5.2 技能编排中的“死锁”问题与解决死锁是编排里比较隐蔽的问题。举个例子技能 A 等待技能 B 的输出技能 B 又等待技能 A 的输出两个技能互相等待整个流程就卡住了。这种情况通常发生在并行编排里。解决方法是明确依赖关系避免循环依赖。在定义工作流时可以用有向无环图来检查依赖关系确保没有环。另一个常见的死锁场景是资源竞争。比如两个技能都要写同一个文件一个在写的时候另一个在等如果第一个技能因为某种原因卡住了第二个就永远等下去。解决方法是给资源加锁或者设置超时。5.3 独家避坑技巧我从实际项目里总结的几条经验第一条技能定义要“薄”不要“厚”。我一开始总想把一个技能定义得特别完整把所有可能的情况都覆盖到。结果就是技能定义文件长得像一本书AI 读起来费劲执行起来也容易迷路。后来我改成“一个技能只做一件事”需要复杂逻辑就用编排来解决效果好很多。第二条永远给技能加超时。不管是执行命令还是调用 API都要设置超时。我遇到过 AI 执行一个网络请求对方服务挂了AI 就一直等等了十分钟才报错。加了超时之后30 秒没响应就直接失败然后走错误处理流程。第三条日志要详细到“能复现”。技能执行失败时日志里要包含足够的上下文信息让你能够手动复现问题。我通常会在日志里记录当前技能名、输入参数、执行时间、原始输出、错误信息。这样排查问题时不用猜。第四条定期审查技能定义。项目在演进技能定义也要跟着更新。我每个月会花半小时过一遍所有技能定义看看有没有过时的、有没有可以合并的、有没有需要拆分的。这个习惯帮我避免了很多“技能定义和实际需求脱节”的问题。5.4 关于账号与权限的常见疑问很多人会问Claude Code 注册账号和不注册有什么区别根据我的使用经验注册账号之后你可以同步配置、保存会话历史、使用云端技能库。不注册的话基本功能也能用但每次换设备都要重新配置。如果你只是临时用一下不注册也没问题但如果是日常开发使用建议还是注册一个。另外如果你在 VS Code 里配置 Claude Code 插件时遇到权限问题可以先检查一下插件的设置项确认 API 密钥或登录状态是否正确。有些企业环境会限制外部 API 访问这种情况下需要联系 IT 部门开通。6. 技能框架的扩展与团队协作6.1 如何把个人技能库变成团队资产一个人用技能框架和一群人用完全是两回事。个人用的时候技能定义怎么写都行反正只有你自己看。但团队用的时候就需要考虑标准化和可维护性。我的做法是在团队里建一个共享的技能库仓库每个人都可以提交新的技能定义但需要经过代码审查。审查的重点不是技能逻辑对不对而是接口定义是否清晰、错误处理是否完整、文档是否齐全。这样能保证技能库的质量避免有人提交一个只有他自己能看懂的技能。另外我们还会定期做“技能复盘”把最近用得比较多的技能拿出来讨论看看有没有优化空间。这个习惯坚持了几个月之后我们的技能库从最初的十几个技能扩展到了五十多个覆盖了日常开发的大部分场景。6.2 技能版本管理与兼容性处理技能定义也是代码也需要版本管理。我们用的是语义化版本主版本号变更表示接口不兼容次版本号变更表示新增功能但向后兼容修订号变更表示 bug 修复。当某个技能的定义发生不兼容变更时我们会保留旧版本一段时间给团队成员迁移的时间。同时在新版本里提供迁移指南说明哪些字段变了、怎么改。兼容性处理的一个关键是不要让技能定义依赖具体的工具版本。比如你写了一个“运行测试”技能里面硬编码了某个测试框架的命令那当团队换框架时这个技能就废了。更好的做法是把命令作为输入参数让调用方来决定用什么命令。6.3 技能框架与现有开发流程的融合最后聊一下融合的问题。superpowers 这套框架不是要取代你现有的开发流程而是要嵌入进去。我们的做法是在 CI/CD 流程里加入技能执行环节比如在代码合并之前自动运行“代码审查”技能在部署之前自动运行“安全检查”技能。这样做的的好处是技能框架不再是“额外的工作”而是开发流程的一部分。团队成员不需要刻意去想要不要用技能流程会自动触发。当然融合的过程中也会遇到阻力。有些人会觉得“多了一层东西变麻烦了”。我的经验是先从一两个痛点场景开始让大家看到效果之后再逐步推广。比如我们先在代码审查环节引入技能大家发现 AI 审查比人工审查快很多而且能发现一些容易忽略的问题接受度就上来了。7. 关于这套框架的一些个人体会我用 superpowers 这套思路大概有半年时间了最大的感受是它逼着我把“怎么做”想清楚。以前用 AI 编程工具很多时候是“试试看”让 AI 自由发挥。现在写技能定义的时候我必须把每一步都拆解清楚把输入输出都定义明白。这个过程本身就是在梳理自己的开发方法论。另一个体会是技能框架的价值不在于自动化而在于标准化。自动化只是结果标准化才是核心。当你把开发流程拆解成一个个标准化的技能之后你会发现很多以前模糊的地方变得清晰了。比如“代码审查”到底审什么、按什么标准审、审完之后怎么处理这些以前靠感觉的事情现在都有了明确的定义。如果你也想尝试这套框架我的建议是从一个小场景开始不要贪大。先选一个你每天都要做的、流程比较固定的任务把它拆解成技能定义跑通之后再逐步扩展。我一开始就想搞一个大而全的框架结果折腾了两周都没跑通后来缩小范围只做“代码提交前检查”这一个场景两天就搞定了。最后分享一个小技巧技能定义写完之后先自己手动执行一遍。按照技能定义的步骤一步一步手动操作看看有没有遗漏、有没有顺序问题、有没有边界情况没考虑到。这个“手动验证”的步骤能帮你发现大部分问题比直接让 AI 跑要高效得多。