1. 从“superpowers”这个热词说起：它到底是什么
第一次看到“superpowers”这个词，很多人会下意识地联想到超级英雄电影里的超能力。但在开发者的语境里，它其实指向一个非常具体的东西——一套围绕 AI 编程助手（尤其是 Codex 这类工具）构建的技能扩展机制。你可以把它理解成给 AI 助手装上一套“外挂技能包”，让它在处理特定任务时，不再只是泛泛地回答问题，而是按照预设的专业流程去执行。
我最初接触这个概念，是因为在几个技术社区里频繁刷到“superpowers 使用指南”“codex superpowers”这类搜索词。当时我的第一反应是：这又是一个营销包装出来的概念吧？但真正上手用了一段时间之后，我发现它解决的是一个非常实际的痛点——AI 助手很聪明，但它不知道你的项目规范、你的代码风格、你的工作流程。每次对话你都要重复交代一遍背景，效率极低。而 superpowers 这套机制，本质上是把这些“隐性知识”固化下来，变成 AI 可以随时调用的技能。
这篇文章适合几类人看：一是已经在用 Codex 或其他 AI 编程助手，但觉得“它总是差那么点意思”的开发者；二是听说过 superpowers 但不知道从哪下手的新手；三是想给自己团队搭建一套 AI 协作规范的技术负责人。我会从概念、安装、配置、实战、踩坑几个维度，把我知道的东西全部倒出来。
需要先说明一点：superpowers 本身不是一个独立的软件，它更像是一套约定和工具集的组合。它的核心价值在于“技能（skill）”这个概念——每个 skill 就是一段结构化的指令，告诉 AI 在特定场景下应该怎么做。这个思路其实和传统的“提示词工程”一脉相承，但比零散的提示词要系统得多。
2. superpowers 的核心机制：技能是怎么被组织和调用的
2.1 一个 skill 的解剖结构
要理解 superpowers，首先得搞清楚一个 skill 到底长什么样。根据我的实际使用经验，一个典型的 skill 通常包含这么几个部分：触发条件、执行步骤、输出规范、边界约束。触发条件决定了 AI 在什么情况下会启用这个技能；执行步骤是核心，描述了具体的操作流程；输出规范约束了结果的格式；边界约束则告诉 AI 哪些事情不要做。
举个具体的例子。假设你要做一个“代码审查”的 skill，触发条件可能是“当用户提交了一段代码并请求审查时”；执行步骤会包括“先检查命名规范、再检查边界条件、然后检查错误处理、最后检查性能隐患”；输出规范可能是“按严重程度分级列出问题，每条问题附带修改建议”；边界约束则是“不要重写用户的代码，只给建议”。
这种结构化的好处在于，它把原本散落在你脑子里的“审查经验”变成了可复用、可传递的资产。我以前带新人的时候，最头疼的就是“怎么把我知道的东西教给他”，现在有了 skill 机制，我可以直接把审查规范写成 skill，新人用 AI 助手的时候自然就按照这个规范走了。
2.2 技能之间的组合与优先级
单个 skill 能解决的问题有限，superpowers 真正强大的地方在于技能的组合。在实际项目中，一个任务往往需要多个 skill 协同工作。比如你要开发一个新功能，可能先调用“需求分析”skill，再调用“架构设计”skill，然后调用“代码生成”skill，最后调用“测试用例编写”skill。
这里就涉及到一个优先级和冲突处理的问题。我的经验是，skill 之间要有明确的层级关系。底层 skill 处理通用逻辑，上层 skill 处理特定场景。当两个 skill 的指令发生冲突时，应该由更具体、更贴近当前场景的那个 skill 说了算。这个原则听起来简单，但在实际配置中很容易搞乱。我见过有人把几十个 skill 平铺在一起，结果 AI 每次都要在大量指令中“纠结”，输出质量反而下降了。
提示：skill 不是越多越好。我建议初期控制在 5 到 8 个核心 skill，等跑顺了再逐步扩展。每增加一个 skill，都要问自己：它解决的是不是一个真实存在的、高频的问题？
2.3 为什么这套机制比传统提示词更有效
很多人会问：我直接写一段详细的提示词不就行了吗，为什么要搞这么复杂？这个问题我认真想过。答案是：提示词是一次性的，skill 是可积累的。你写一段提示词，用完就散了，下次还得重新写。而 skill 是存在文件里的，可以版本控制、可以分享、可以迭代。
更重要的是，skill 机制强制你把“隐性知识”显性化。当你试图把一个经验写成 skill 的时候，你会发现自己其实有很多“说不清楚”的地方。这个过程本身就是一次知识梳理。我在写第一个 skill 的时候，光是“什么算好的错误处理”这一条，就反复改了五六遍，因为写着写着发现自己的标准其实并不统一。
从技术实现角度看，superpowers 通常是通过在项目目录下放置特定格式的配置文件来工作的。AI 助手在启动时会读取这些文件，把它们加载到上下文中。这就意味着，你的 skill 是项目级别的，不同的项目可以有不同的 skill 集合。这一点非常关键，因为后端项目和前端项目需要的技能显然不一样。
3. 从零开始：superpowers 的安装与环境准备
3.1 前置条件与版本确认
在动手安装之前，有几件事必须先确认清楚。首先是你用的 AI 助手工具是否支持 skill 机制。目前来看，Codex 系列对这套机制的支持比较完善，但不同版本之间差异很大。我建议先去官方文档确认一下你当前使用的版本是否包含这个功能。
其次是运行环境。如果你是在本地开发，需要确保你的项目目录有足够的权限让 AI 助手读取配置文件。我遇到过一次很隐蔽的问题：skill 文件明明放在那里，但 AI 就是读不到，排查了半天才发现是文件权限的问题。所以建议在安装前先检查一下目录权限，尤其是团队协作场景下，不同成员的权限设置可能不一致。
还有一个容易被忽略的点是编码格式。skill 文件通常包含大量中文或特殊字符，如果编码不统一，AI 读取时会出现乱码，导致技能失效。我的做法是统一使用 UTF-8 编码，并且在文件头部加上编码声明。这个细节看起来不起眼，但踩过一次坑之后你就会记住。
3.2 安装步骤的详细拆解
安装过程本身其实不复杂，但每一步都有讲究。我把它拆成几个阶段来说。
第一步是获取 skill 模板。你可以从社区里找现成的模板，也可以自己从零写。我的建议是先用现成的模板跑通流程，再根据自己的需求修改。社区里有一些质量不错的开源 skill 集合，覆盖了代码审查、文档生成、测试编写等常见场景。
第二步是放置文件。通常需要在项目根目录下创建一个特定的文件夹（不同工具可能命名不同，常见的是.skills或skills），然后把 skill 文件放进去。这里要注意的是，文件夹的命名和位置必须严格按照工具的要求来，不能随意改动。
第三步是验证加载。放好文件之后，不要急着用，先让 AI 助手执行一个简单的任务，看看它是否读取到了 skill。我通常的做法是故意在 skill 里写一条很显眼的规则，比如“所有输出必须以‘收到’开头”，然后看 AI 的输出是否符合。如果不符合，说明 skill 没有被正确加载。
第四步是调试与迭代。第一次加载成功不代表 skill 写对了。你需要在实际使用中观察 AI 的行为，看看它是否按照你预期的流程执行。很多时候，AI 会“部分执行”你的 skill——大方向对了，但细节跑偏了。这时候就需要回到 skill 文件，把模糊的地方写得更具体。
3.3 环境配置中的常见陷阱
说几个我踩过的坑。第一个是路径问题。有些工具要求 skill 文件必须放在特定路径下，但文档写得不清楚，我试了好几个位置才找对。如果你也遇到类似情况，建议直接去看工具的源码或者社区讨论，比翻文档快。
第二个是缓存问题。AI 助手可能会缓存 skill 文件的内容，你修改了文件但 AI 用的还是旧版本。解决办法通常是重启助手或者手动清除缓存。这个坑很隐蔽，因为你会以为是自己 skill 写错了，实际上是缓存没更新。
第三个是多项目冲突。如果你同时在多个项目里使用 superpowers，要小心 skill 之间的相互干扰。我的做法是每个项目用独立的 skill 集合，不要跨项目共享，除非那个 skill 确实是通用的。
4. 写出第一个可用的 skill：以代码审查为例
4.1 明确 skill 的目标和边界
写 skill 最忌讳的就是“什么都想要”。我见过有人试图写一个“万能 skill”，结果 AI 执行起来一团糟。正确的做法是一个 skill 只解决一个明确的问题。这里我以“代码审查”为例，完整走一遍编写流程。
首先要明确这个 skill 的目标：当用户提交代码时，AI 应该按照预设的规范进行审查，并输出结构化的审查报告。边界是：只审查，不修改；只给建议，不强制；聚焦于可维护性和正确性，不纠结于个人风格偏好。
这个目标和边界的定义非常重要。如果你不写清楚边界，AI 可能会过度发挥，比如直接把你的代码重写了，或者对一些无关紧要的格式问题大做文章。我在早期就吃过这个亏，AI 把我一段能跑的代码改得面目全非，理由是“更符合最佳实践”，但实际上引入了新的 bug。
4.2 分步骤编写 skill 内容
skill 的内容通常用自然语言写，但要有清晰的结构。我一般按照“角色定义 → 审查维度 → 输出格式 → 约束条件”这个顺序来写。
角色定义部分，告诉 AI 它现在是一个“资深代码审查员”，有十年以上的经验，注重实用性和可维护性。这部分看似虚，但实际上会影响 AI 的语气和判断标准。
审查维度部分，列出具体的检查项。我的清单包括：命名是否清晰、函数是否过长、边界条件是否处理、错误处理是否完善、是否有明显的性能问题、是否有重复代码。每个维度下面再给一两个具体的判断标准，比如“函数超过 50 行视为过长”。
输出格式部分，规定审查结果的呈现方式。我要求 AI 按“严重 / 中等 / 轻微”三个等级分类，每条问题附带代码位置和修改建议。这样我拿到结果之后可以直接对照修改，不用再二次整理。
约束条件部分，明确写出“不要做什么”。比如“不要重写代码”“不要评论代码风格偏好”“不要提出无法落地的建议”。这些约束能有效防止 AI 跑偏。
4.3 测试与迭代：怎么判断 skill 写得好不好
写完 skill 之后，必须用真实场景测试。我的测试方法是：准备三到五段有代表性的代码，包括一段有明显 bug 的、一段写得不错的、一段边界情况复杂的。然后让 AI 分别审查，看输出是否符合预期。
判断标准有三个：覆盖率（该发现的问题是否都发现了）、准确率（提出的问题是否真实存在）、可操作性（建议是否具体可执行）。如果覆盖率低，说明审查维度不够全；如果准确率低，说明判断标准太模糊；如果可操作性差，说明输出格式需要调整。
我自己的第一个代码审查 skill 改了四版才勉强能用。第一版太笼统，AI 只会说“代码质量不错”这种废话；第二版太严格，把正常的代码也批了一顿；第三版覆盖率上来了但误报太多；第四版才找到平衡点。这个过程很磨人，但一旦跑通，后面就轻松了。
5. 把 superpowers 接入日常工作流：几个真实场景
5.1 场景一：新项目初始化时的规范落地
每次开新项目，最烦的就是“定规范”这件事。团队里每个人都有自己的习惯，讨论来讨论去浪费时间。现在我的做法是：项目初始化时，直接把规范写成 skill 文件放进项目里。这样从第一天起，AI 助手就会按照这个规范辅助开发。
具体来说，我会写一个“项目规范”skill，内容包括目录结构约定、命名规范、提交信息格式、依赖管理原则等。当团队成员用 AI 助手写代码时，AI 会自动按照这些规范来生成代码和建议。这比写一份没人看的文档有效多了。
实测下来，这个做法能把新项目的“规范磨合期”从两三周缩短到几天。因为规范不再是纸面上的文字，而是嵌入到了日常工具里，你不想遵守都难。
5.2 场景二：代码审查的自动化前置
传统的代码审查是“人审人”，效率低且容易漏。我现在会把代码审查 skill 配置成“提交前自动触发”。也就是说，开发者写完代码准备提交时，AI 助手先跑一遍审查，把明显的问题拦下来。这样人工审查就可以聚焦在架构和业务逻辑上，不用再纠结命名和格式。
这个流程的关键是审查 skill 的质量。如果 skill 误报太多，开发者会烦，最后直接跳过。所以我在配置时会设置一个“置信度阈值”，只有 AI 比较确定的问题才会被拦下来，不确定的只做提示不阻断。
5.3 场景三：文档与注释的同步生成
写文档是大多数开发者的噩梦。我的做法是写一个“文档生成”skill，要求 AI 在生成代码的同时，自动生成对应的注释和接口文档。这个 skill 的约束是：注释要解释“为什么”而不是“是什么”，接口文档要包含参数说明、返回值说明和调用示例。
这个场景下，skill 的难点在于平衡详细度和简洁度。太简略了没用，太详细了没人看。我最后的方案是分两级：代码内注释保持精简，只写关键决策点；独立的接口文档则详细展开。AI 会根据上下文自动判断该用哪一级。
6. 踩坑实录：那些让我抓狂的问题和解决过程
6.1 skill 不生效的排查链路
有一次我花了一个下午写了一个自认为很完美的 skill，结果 AI 完全不理会。排查过程是这样的：先确认文件位置对不对，没问题；再确认文件格式对不对，也没问题；然后检查编码，发现是 GBK 而不是 UTF-8，改过来之后还是不行；最后发现是文件名的锅——我用了中文文件名，工具不识别。
这个经历告诉我，排查问题要按从外到内的顺序：先看文件系统层面（位置、权限、编码、命名），再看内容层面（格式、语法），最后看逻辑层面（指令是否清晰）。很多人一上来就怀疑自己 skill 写错了，其实问题往往出在更外层。
6.2 指令冲突导致的“精神分裂”
另一个让我头疼的问题是 skill 之间的指令冲突。我有两个 skill，一个说“生成代码时要详细注释”，另一个说“保持代码简洁”。结果 AI 在生成代码时一会儿加一堆注释，一会儿又全删掉，输出极不稳定。
解决办法是建立明确的优先级规则。我在 skill 文件的头部加了一个“优先级”字段，数字越小优先级越高。当冲突发生时，AI 按照优先级高的 skill 执行。同时，我会定期审查 skill 集合，把功能重叠的合并掉，从根源上减少冲突。
6.3 过度依赖 skill 导致的能力退化
这个问题比较隐蔽，但值得警惕。有一段时间我几乎把所有事情都交给 skill 处理，结果发现自己对某些基础知识的掌握反而生疏了。比如以前我能手写复杂的正则表达式，后来习惯了让 AI 生成，再自己写的时候居然卡壳了。
我的建议是：把 skill 当作放大器，而不是替代品。它应该帮你处理重复性工作，让你有精力去思考更重要的问题，而不是让你完全不动脑子。我现在的做法是，关键逻辑自己先想清楚，再用 skill 辅助实现和检查。
7. 进阶玩法：让 skill 随项目一起成长
7.1 版本化管理 skill 文件
skill 文件应该像代码一样被版本管理。我的做法是把 skill 目录纳入 Git 仓库，每次修改都提交，并且写清楚修改原因。这样做的好处是，当 AI 的行为发生变化时，你可以回溯到是哪个 skill 的哪次修改导致的。
更进一步，我会给 skill 文件打标签，比如v1.0-稳定版、v1.1-实验性。在项目里可以配置使用哪个版本的 skill，这样即使新版本有问题，也能快速回滚。
7.2 根据项目反馈持续优化
skill 不是写完就完了，它需要根据实际使用反馈持续优化。我会定期收集团队成员的反馈，看看哪些 skill 经常被绕过、哪些 skill 的误报率高、哪些场景缺少对应的 skill。
优化的方向通常有三个：细化判断标准（把模糊的规则写具体）、补充边界情况（把没想到的场景加进去）、调整输出格式（让结果更易读易用）。每次优化之后，都要重新跑一遍测试用例，确保没有引入新的问题。
7.3 团队协作中的 skill 共享机制
如果是团队使用，skill 的共享就很重要。我的做法是建立一个“skill 仓库”，每个人都可以提交自己的 skill，但需要经过 review 才能合并。review 的标准包括：目标是否明确、边界是否清晰、是否经过测试、是否与现有 skill 冲突。
同时，我会维护一份“skill 索引”，列出每个 skill 的功能、适用场景、维护者。这样新成员加入时，能快速了解团队有哪些可用的 skill，不用从头摸索。
8. 关于 superpowers 的一些个人体会
用了大半年 superpowers 之后，我最大的感受是：它改变的不是 AI 的能力，而是我和 AI 协作的方式。以前我把 AI 当成一个“什么都知道但什么都不精”的顾问，现在我把 AI 当成一个“经过培训的团队成员”。这个心态转变很关键。
另一个体会是，skill 的质量取决于你对业务的理解深度。如果你自己对某个流程都说不清楚，写出来的 skill 一定是模糊的。所以写 skill 的过程，其实也是逼自己把问题想清楚的过程。我有很多次是在写 skill 的时候，才发现自己对某个环节的理解有漏洞。
最后说一个实用的小技巧：从最小的 skill 开始。不要一上来就写一个覆盖整个开发流程的巨型 skill，那样大概率会失败。先写一个只解决一个小问题的 skill，跑通之后再加下一个。这样每一步都有正反馈，也更容易定位问题。我现在项目里的 skill 集合，就是从最初的一个“提交信息格式化”skill 慢慢长出来的。
