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 慢慢长出来的。