1. 这到底是个什么东西为什么AI编程工具需要一个“技能系统”先说明一个背景。如果你用过Claude Code或者Codex这类AI编程工具多半会有一种很微妙的体验它们确实聪明能写代码、能改文件、能跑测试但每次开一个新会话它就像失忆了一样——你上一次整理好的项目结构、你偏好的事务处理方式、你常用的代码规范它全都忘了。你得重新把需求讲一遍它还是可能给出一个和之前完全不同的方案。遇到稍微复杂的任务它做着做着就会跑偏不在说好的文件里改、绕过既有的设计模式、把简单问题往复杂里整。superpowers这个项目解决的正是这个“每一次都从零开始”的痛点。它不是某个具体的AI模型而是一套给Claude Code / Codex这类编程代理用的“技能增强库”。用我自己的话说它把AI从一个“每次都要重新教的新实习生”变成“一个自带工作习惯和专业知识的老员工”。这里的“技能”不是那种游戏里放个光波的超能力而是一套严谨、可复用、结构化的任务处理能力每个技能包含一份行为说明文档、可选的辅助脚本、明确的工作流规范以及触发它的条件描述。当AI在对话中发现当前任务匹配某个技能时它就会主动加载并执行对应的处理流程。这套东西最吸引我的地方在于它重新定义了人机协作的方式。传统做法里我们对AI的约束靠的是“提示词”比如“你是一个资深的Java工程师”“请遵循TDD流程”。可提示词是软的AI高兴了听不高兴了假装没看见。superpowers把提示词升级成了“工程化技能包”技能里的每一条规则、每一个步骤都是被结构化组织起来的甚至还能挂载可执行的脚本。这就相当于从“口头嘱咐”升级到“给AI配了一本完整的操作手册加工具包”。从适用人群来说我觉得有三类人能从中得到实实在在的好处第一类已经在重度使用Claude Code或Codex做日常开发的人这类人能立刻感到效率变化第二类对AI编程感兴趣、但总觉得AI“不够靠谱”的开发者这套技能库能让你看到AI被约束后的样子第三类团队技术管理者——你会发现团队的代码规范、架构约束、开发流程竟然可以通过这种技能包的方式沉淀下来分发给每个开发者的AI助手。文章后面我会通过一个Java项目里写API接口的实际案例把核心的设计、安装和实操步骤完整展开保证你照着做就能把项目跑起来。2. 它是怎么设计出来的拆解superpowers的核心工作方式2.1 无状态AI的“记忆困境”要理解superpowers的价值得先理解AI编程工具目前最让人头疼的问题。无论是Claude Code还是Codex它们的工作形态是“会话式”的每次对话开始时模型只有预训练时的通用知识加上你的输入上下文。它记不住昨天的会话也不知道你当前项目的隐性约定。比如你的项目里有个不成文的规定所有数据库操作必须走Repository层不允许直接在Controller里写JDBC。这种约定只存在于你的脑子里或者某个角落里落灰的文档里。每次你让AI加个接口它都会大概率直接对着Controller“自由发挥”。你或许会说那我每次都把规范贴在提示词里不就行了吗理论上可以但实际上很累。一段超过三屏的规范说明每次开新会话都要重新贴一遍而且随着项目演进规范会变你贴的旧规范反而会误导它。superpowers的核心思路就是解决这个“记忆与规范化”问题——把那些希望AI遵循的规范、流程、经验打包成一个一个独立的“技能”放在一个固定的目录里。AI启动时会读取一个索引文件知道当前有哪些技能可用。当任务描述和某个技能的触发条件匹配时AI会自动加载该技能的完整文档并在接下来的交互中按技能定义的流程行事。2.2 技能不只是文档还是一套“可执行”的流程我看过很多类似的“prompt库”项目大家把提示词收集起来按照场景分类写一堆精美的markdown。但真用起来效果有限因为AI模型在生成代码时对上下文的遵循程度并不稳定。superpowers的聪明之处在于它不把技能限制在“文字描述”层面而是允许每个技能携带一个或多个可执行的辅助程序。这些程序可以是Python脚本、Shell脚本、Node.js程序甚至是一段被调用时执行的外部工具命令。技能中的文字描述负责“指导AI怎么想”而脚本则负责“接管AI不擅长的确定性工作”。举个例子。项目里有一条内置技能叫“根据代码库结构理解项目”当AI进入一个新项目时它不会瞎猜而是会按照技能里定义好的步骤去扫描目录结构、读关键配置文件、定位入口和测试用例。它能运行一个脚本自动帮它生成一份“项目地图”然后基于这份地图和你对话。这种做法本质上把AI的“摸索过程”变成了“按图索骥”效率和准确度都高了一大截。再解释一下这个机制的本质你可以把每个技能想象成一个“函数”技能有一个描述性的函数名name一个说明何时调用的注释description以及一段函数体工作流定义或脚本实现。AI扮演的是“调度器”的角色它会根据用户当前的请求判断该调用哪个技能技能被触发后AI会切换成“执行者”模式严格参照技能内部定义的步骤推进。这种“调度-执行”分离的设计我认为是整个superpowers项目最值得学习的思想它没有试图把流程写死在代码里而是把流程交给AI选择但确保AI一旦选择就有据可依。2.3 技能之间怎么协作driving模式与编排思想大家可能听说过一个概念叫“chat-oriented programming”就是让AI通过对话来驱动整个编码过程。superpowers里有一种“driving”模式——我理解得更直白一点就是把AI从“问一句答一句的小工”变成“能够自己制定计划并逐步推进的项目经理”。它的做法是先把一个大任务拆解成一系列小的、可验证的步骤然后让AI带着你用户按步骤走每完成一步就同步进度遇到分歧停下来讨论。这种编排能力不是靠单个技能完成的而是多个技能之间的协作。比如在处理一个Java Spring Boot项目时superpowers会组合“项目结构分析”技能、“数据库Schema检查”技能、“测试先行”技能甚至“代码审查”技能。AI会拿着“项目结构分析”技能产出的地图找到Service层的位置然后根据“数据库Schema检查”的输出来确定实体字段紧接着按照“测试先行”的流程先写测试最后交给“代码审查”技能挑毛病。这个过程我能说得很具体是因为我自己用类似思路处理过一个微型Spring项目整体流程和结果都比较理想下面第三部分会展开讲。2.4 与自己开发的“用”和“造”的辩证关系superpowers还有一个很人性化的设计它不仅给你一套已经配好的内置技能还留了一条完整的“技能作者”路径。也就是说你不只是使用者你还可以是创造者。项目里的skills-authoring-guide就是教你如何构建自己技能的教程。我认为这一点才是它生命力所在。每个团队、每个项目都有自己独特的流程和规范永远想靠现成的技能包解决所有问题是不现实的。而只要你理解了技能包的目录结构、SKILL.md的编写规则你就能像写接口文档一样把团队经验“翻译”成AI能读懂的技能。这条路径的存在让项目本身有了“自我进化”的能力。3. 从初始化到人手一个技能安装与运行环境的完整实操3.1 需要准备的运行环境在动手之前先把基础条件列一下。我自己是在macOS上操作的但Linux和Windows通过WSL也完全可行。你需要准备的东西有Node.js环境Claude Code本身是基于Node.js的版本建议18以上20 LTS最好。Git用于克隆项目仓库。Claude Code或Codex CLI这两个工具二选一。Claude Code需要你有一个能够访问Anthropic API的账号并且命令行登录状态有效Codex则需要OpenAI的CLI环境。安装好其中一个后请先随便跑一个任务确认能正常对话、能读写文件再继续下面的操作。这里有一个小提醒如果你之前没有装过Claude Code可以先执行npm install -g anthropic-ai/claude-code完成全局安装。装完之后在终端输入claude如果能看到交互界面或者命令提示符就说明环境就绪。整个过程不需要动Anthropic的API密钥它走的是OAuth登录流程。3.2 拉取项目与初始化技能目录环境准备好以后就可以开始拉取superpowers了。它在GitHub上的仓库名就叫obra/superpowers直接克隆到你方便管理的位置。我习惯放在~/workspace/下这样既和普通项目分开又方便备份。cd ~/workspace git clone https://github.com/obra/superpowers.git cd superpowers克隆完成后项目里会有一个安装脚本大概率是install.sh或者类似名字。运行它之前建议先看一眼脚本内容确认它做了哪些操作。这个习惯不管用什么开源项目都值得保持——不要盲目信任第三方脚本花三十秒看看它到底往你机器上写了什么能避免很多麻烦。以我看到的版本为准脚本核心做两件事情第一把skills目录复制到你的全局配置目录下第二在Claude Code的配置文件中注册这个技能目录让AI启动时能加载到技能索引。./install.sh执行完install脚本以后如果你用的是Claude Code实际上还有一个初始化动作要做——在Claude Code会话里输入superpowers它会触发一个引导流程把一些额外的子代理配置写到项目里。这一步的目的是把superpowers附带的“模式”注册到当前项目上下文。如果你是第一次接触这些概念不用着急按提示点allow允许它生成配置就行。看到类似“superpowers initialized”的反馈就算成功。3.3 验证安装是否成功安装完以后怎么确认它真的生效了最直接的验证方式是在Claude Code会话里输入/skills看能否列出当前可用的技能清单。如果能看到一组带有描述的技能列表比如“claude-architecture”“code-reviewer”“test-driven-development”这些说明技能索引已经被正确加载。另一种方式更贴近实际你直接说一句“帮我看一下这个项目的结构”然后观察AI的行为。如果它不再像之前那样随口回答而是表现出“先扫描目录、再分析框架、最后给出结构说明”的一整套动作那基本可以确认superpowers的“项目分析”技能已经被触发了。我初次安装时踩过一个不算坑的坑因为我用的Shell是zsh但在install之前没有把Claude Code的路径导入到PATH环境变量里导致安装脚本找不到claude可执行文件报了一个“command not found”。解决办法很简单先把Claude Code安装路径确认清楚确保在任意新终端里输入claude都能启动再回去跑install脚本。如果你用的是Windows上的WSL还要额外注意一下文件权限——.sh脚本可能默认没有x权限可以先给脚本加上执行权限再运行。chmod x install.sh ./install.sh4. 核心技能怎么用一个Java项目的实战拆解4.1 用“项目地图”技能摸清代码库很多人在AI编程工具上有一个高频率场景接手一个陌生项目想快速了解它然后完成一个具体的改动需求。在没有技能库的时候AI的做法一般是“随机问几个问题然后试探性地改几个文件”结果经常把不该改的地方改了。有了superpowers之后流程就完全不一样了。我在一个Spring Boot的微服务工程上跑过一次完整的“添加一个用户查询接口”的需求。第一步我先在对话里丢了一句帮我在现有项目里加一个查询用户详情的接口。按理说这么模糊的需求AI应该会追问很多东西——查哪张表返回什么字段接口放在哪个模块但superpowers没有这么干。它先触发了“项目地图”相关技能开始扫描文件树、读取pom.xml里的依赖、翻application.yml里的数据源配置然后花了不到一分钟时间输出了一张结构化的项目概览包括这是一个标准的controller-service-mapper三层结构用户相关的表实体是UserProfile对应的Mapper接口在com.example.user.mapper包下项目里已经有一个UserService只是没有查询详情的方法所有接口返回结果统一包裹在ResultT这个类里。这段输出看起来平平无奇但如果你用“裸奔”的Claude Code做过类似任务就会知道这个信息多值钱。它从根本上杜绝了“AI到Controller里新开一个方法还用了个不存在的返回类型”这种低级错误。4.2 “测试先行”技能改变编码顺序拿到项目地图后我并没有直接说“给我写接口”。基于superpowers里的“test-driven-development”技能整个后续步骤被编排成了红绿重构模式。有意思的是AI不是嘴上说“我们来写测试”而是真的先创建了一个新的测试类UserControllerTest里面先写好期望的接口行为——比如调用GET /user/123应该返回该用户的JSON数据。测试跑起来自然是红失败因为它依赖的Service方法还不存在。此时它才进入第二步根据测试的定义在Service层补上getUserById(Long id)方法再在Mapper层加上对应的SQL查询。整个实现过程非常克制完全没有超出测试定义的范围。最后跑测试变绿再顺手做了微小重构——把方法名从queryUser统一为getUserById。这套流程如果你让AI自己“自由发挥”它大概率会跳着做先嫌测试麻烦直接开写实现然后补一个简单的“冒烟测试”装装样子。但有了技能约束它就会老老实实按照步骤来。这背后不是模型突然变自律了而是技能文档里明确写着“先写失败的测试、运行确认失败、再实现、运行确认通过”并且这些约束被强有力地传递到了对话上下文中。4.3 “代码审查”技能给出的批评意见许多人很享受AI快速产出代码的感觉但很少让AI去审查自己的代码。superpowers里内置的“code-reviewer”技能让我眼前一亮。在我完成上面的接口开发后我说了一句“帮我看看这段代码有什么问题”它立刻加载审查技能从几个维度给出了意见安全性GET /user/{id}缺少参数校验负数ID会导致无效SQL查询架构一致性Controller直接注入了Mapper这和其他接口的Service层隔离风格不一致异常处理查询不存在用户时应返回业务码40401而不是裸空值可测试性随机数生成逻辑嵌入在业务方法里导致测试不可重复。每条意见都对应到具体代码行并且给出了修改建议。这种体验坦白说比很多公司的代码评审来得还扎实。我认为这件事背后的核心价值在于AI原本“偏科”——擅长写新代码不擅长批判自己刚写完的代码。而“code-reviewer”技能通过强制切换思维模式让AI从一个“执行者”变为“审查者”从不同角度重新审视同一段代码。同一份能力两种角色只需要一个技能文档做引导。4.4 技能库如何规避Java项目的常见套路再补充一点关于Java项目特有的经验。Spring Boot项目顺手的AI最容易犯的错误包括往Controller里堆业务逻辑、忽略事务注解、不处理空指针、无视项目已有的异常处理体系。这些通病其实都可以通过技能描述来约束。你可以自己在SKILL.md里写上这样一条规则### 3. 实现约束 - 所有数据库操作必须通过对应的Mapper接口禁止在Controller中直接引用JdbcTemplate或EntityManager。 - 涉及事务的服务方法必须显式标注Transactional(rollbackFor Exception.class)。 - 所有对外返回统一使用ResultT包装禁止直接返回实体类。当这条规则被写进团队的技能库后每一次新会话里的AI都会自动遵循。这比你在聊天里反复强调“记得用Result包装”要可靠得多。从这个角度看技能的“编写”比“使用”更重要也是我把技能的编写实践放在下面这个部分单独讲的原因。5. 定制自己的技能包从零搭建一个私有技能5.1 技能的标准目录结构理解了技能的价值后下一步自然是动手建一个属于自己的技能。superpowers规定了一个标准的目录规范看起来很清晰每个技能是一个独立文件夹文件夹的名称就是技能名建议用小写字母加连字符文件夹内必须有一个SKILL.md文件它承担技能说明书的功能。如果技能需要辅助脚本可以再放一个scripts子目录需要示例代码就放examples子目录。整体结构大概是这样skills/ my-java-api-handler/ SKILL.md scripts/ generate_api_test.sh examples/ getUserById.example.md这个结构让我联想到一个很熟悉的原子概念一个技能包就是一个“可独立交付的模块”它有接口触发条件、有实现工作流和脚本、有文档SKILL.md。当你在团队内部共享技能时只需要把这个文件夹发给别人或者推到Git仓库对方的AI工具就能加载同样的能力。5.2 SKILL.md的编写规范前置元数据与主流程SKILL.md是整个技能的核心它在结构上由两部分组成开头的YAML前置元数据和正文的Markdown流程描述。YAML部分虽然字段不多但直接决定AI什么时候触发它。以下是字段的基本解释name技能名建议保持和文件夹名一致description技能的一句话描述这里面写的关键字越精准AI越容易在合适场景触发它when_to_use明确列出适合触发该技能的场景避免AI误用version技能版本号改了内容记得把这个数值同步更新。正文部分则自由一些但一个好的实践是分段组织先是一个“技能概览”帮助AI快速理解整体目标然后是“工作流步骤”用有序列表写出一步步执行的内容再是“约束与禁止事项”强调哪些事绝对不能做。举个例子我给我自己的Java API开发技能写过这样一个SKILL.md骨架--- name: java-api-development description: 用于在Spring Boot项目中新增或修改RESTful API接口。当用户要求添加接口、修改接口或调整Controller时使用该技能。 when_to_use: 当任务涉及创建新的Controller方法、Service方法、Mapper查询或修改现有接口行为时。 version: 1.2.0 --- # Java API Development ## 技能概览 本技能指导AI在Spring Boot项目中新增REST接口的完整流程覆盖Controller、Service、Mapper三层并确保代码符合项目的统一风格。 ## 工作流步骤 1. 检查项目现有代码风格重点查看一个已有Controller的实现方式作为参考。 2. 根据任务需求确定接口的HTTP方法、URL路径和请求参数。 3. 在Service层编写业务方法若需要事务则添加Transactional(rollbackFor Exception.class)。 4. 在Mapper层编写必要的SQL语句确认参数映射无误。 5. 在Controller层暴露接口…… 6. 使用项目的测试基类编写接口测试验证成功路径和异常路径。 ## 约束与禁止事项 - 禁止在Controller中直接编写业务逻辑或SQL。 - 禁止修改与任务无关的配置文件和代码。 - 新增接口时不得绕过已有的ResultT统一返回结构。 - 所有新增依赖必须先在pom.xml中声明禁止隐式依赖传递。注意一个细节description字段没有写得太长而是把“当用户要求添加接口、修改接口或调整Controller时”这样的触发信号放进去。AI加载技能时实际上是靠这个字段的语义匹配来决定是否读取整个文档的太宽泛的描述容易导致技能被乱触发太具体的描述又会漏匹配。5.3 如何让技能真正被执行注册与索引写完SKILL.md之后还需要把它放对位置。如果你使用的是Claude Code技能目录一般在两个位置之一全局目录~/.claude/skills/适用于所有项目项目目录.claude/skills/只对当前项目生效。建议个人偏好和团队级规范放在项目目录通用经验和跨项目习惯放在全局目录。两个位置都放好后还需要让AI知道这个技能的存在——注意这个步骤很容易被遗漏。Claude Code启动时有一个“技能索引”的概念如果索引里没有你的技能AI是不会凭空发现的。一种做法是在配置文件的additionalDirectories里显式声明技能目录路径另一种做法如果superpowers的安装脚本已经创建了一个技能索引文件你可以直接修改该文件追加自己的技能路径。修改完成后重启Claude Code会话再用/skills命令验证新技能是否出现在列表中。很多新手写好了技能文档却始终不生效80%的原因是忽略了这一步。5.4 让技能发挥作用的关键描述中的“触发信号”写完技能以后我在多次尝试中总结出的一个心得是SKILL.md的开头描述写得好不好直接决定这个技能是“有用”还是“形同虚设”。描述里应该踩中用户会和AI说的那些高频话术。比如用户通常会说“新增一个接口”“帮我加个查询功能”“这个Controller写得太乱了改一下”那么这些短语就该出现在description或when_to_use里。当你把触发信号埋得足够多且足够真实时AI的语义匹配质量就会有肉眼可见的提升。这其实是一种“面向调用的描述设计”和写接口文档时给方法写一个让人一看就想调的注释是一个道理。6. 安装与使用中的高频问题踩坑记录与排查方法说了这么多亮眼的体验也不得不承认真正落地的时候会遇到各种问题。毕竟它是一个持续迭代的开源项目不可能做到开箱即用、零故障。这里把我在安装和使用中遇到的高频问题和排查思路整理成一个速查表方便遇到异常时快速定位。问题现象可能原因排查与解决办法安装脚本报找不到claude命令Claude Code未安装或不在PATH中先确认claude命令在任意终端中可用再重新执行install脚本技能列表为空/skills没有输出技能目录未被正确注册检查skills目录路径是否在配置文件的additionalDirectories里技能能被列出但对话中不触发技能描述过于宽泛或过于局限重写SKILL.md的description多补充触发场景和用户说法辅助脚本不执行报权限错误脚本文件没有执行权限对脚本执行chmod x设置权限多个技能被同时触发行为混乱技能描述之间存在语义重叠在每个技能的when_to_use中补充互斥条件尽量明确边界使用Codex时部分技能无效Codex和Claude Code对技能目录的读取方式不同查阅Codex官方文档确定它支持的自定义指令目录并重新注册除了表格里的这些还想特别强调两个实操心得。第一个是关于调试当你怀疑某个技能没有生效时与其猜来猜去不如直接在对话里问AI“现在加载了哪些技能为什么选择这个技能”。Claude Code会把它的判断依据说出来这能将问题定位时间缩短一大半。第二个是关于升级superpowers的迭代速度不算慢每次拉取新版本后建议重新执行安装脚本并重启会话。有一次我就是图省事只更新了仓库代码而没有重新跑安装脚本结果新技能一直没有出现在列表里排查了半天才明白是这个原因。如果你接手的是一个遗留Java项目在首次使用superpowers的“项目地图”技能时可能会发现它扫描出来的结构和实际业务逻辑有出入——比如项目里有过时的XML配置或者历史遗留的双层Service。这种情况不要太依赖技能的输出要用人类经验修正一下AI的判断毕竟技能也是基于通用经验构建的不可能天然理解每个项目内部的“潜规则”。7. 除了Claude Code之外聊一聊Java场景下的Codex接入前面大部分操作都是以Claude Code为宿主来展开的但从标题相关的热词来看不少人关心的是codex superpowers的组合。Codex是OpenAI的编程代理工具它和Claude Code确实在很多能力上重叠但在技能加载机制上有区别。我个人的经验是superpowers在Claude Code上的集成度最高很多特性是为它量身定制的在Codex环境中你更多是借助它提供的AGENTS.md机制来承载类似的“技能定义”。如果你确实需要在Codex里模拟superpowers的体验可以这样做把技能中的SKILL.md改写为一个独立的AGENTS.md文件放到项目根目录或者~/.codex/下。AGENTS.md本质上是给AI看的项目说明你用类似的结构把约束条件和工作流写进去Codex启动时就会读取。要注意的是Codex对多技能索引的支持不如Claude Code灵活一个项目通常只读取一个AGENTS.md所以你可能需要把多个技能整合到一个文档里。这种做法效果上不如原生superpowers那么精细但依然可以为你带来部分好处。在Java项目里Codex和superpowers组合的实际效果如何呢我在一个使用Java 17和Spring Boot 3.2的项目上测过一次通过AGENTS.md定义Java API开发规范然后让Codex完成一个分页查询接口的开发。它的行为确实有了明显改善比如会自动使用PageHelper、分页返回值会统一包装。但和Claude Code中使用原生的superpowers相较Codex在触发精确度和流程编排上的细腻程度还是稍逊一些。如果这是你唯一的工具我建议你把AGENTS.md写得尽量偏向“硬约束”把禁止事项和边界写得直白一点减少AI的自由发挥空间。有一点值得留意不论你选择哪个宿主都要注意“技能更新的一致性”问题。如果你的团队在共享一套superpowers技能库每次更新后要确保所有成员的宿主工具都重新加载了新配置。否则很容易出现“老成员的AI还在走老流程”这种团队内协作偏差。8. 写在最后的实践建议把技能当资产而不是脚本用了几个星期后我对superpowers最大的感受是它表面上是一个工具本质上是一种“把经验固化成资产”的工作理念。你在其中投入的每一分钟用于编写SKILL.md、分析触发场景、补充约束条件都是在为你自己的AI助手积累财产。这些财产不会像普通聊天记录一样随会话结束而消失它们会持续在每一次新的会话中生效变成你个人的“数字化老员工”。我个人建议的落地路径是这样的先不要贪多别一口气导入所有技能并试图让AI完成非常复杂的任务。先选一两个和自己日常开发强相关的技能用上一个星期感受一下AI在有约束和没约束下的区别。用顺了之后再花一个下午把你平时工作中最常对AI强调的那两三句话提炼出来写成一个最简单版本的SKILL.md把自己的第一个自定义技能建起来。哪怕它只有十条规则只要每一条都是真实的痛点这个技能给你的价值就会超过任何一份漂亮的现成模板。最后分享一个很多人会忽略的小技巧在写SKILL.md的约束项时多用“必须”“禁止”“不允许”这类强语气词少用“建议”“可以考虑”这类模糊表达。通过我多个技能的实际测试AI对“禁止”级描述的遵循度要明显高于“建议”级描述。这背后的道理很简单模型在生成时会有一个“符合预期”的衡量强约束表达能够显著压缩它的探索空间。想要AI稳定输出就在技能文档里替它划清边界。这大概也是superpowers这个项目名字暗含的意思你给它一把尺子它才能交出超水平发挥的结果。