企业官网建设流程全解析

给 Codex 装上“超能力”：Superpowers Skill 的完整实战指南

最近在折腾 AI 编程工作流的时候，我在社区里刷到一个很有意思的项目叫superpowers。第一反应是这名字起得够狂，第二反应是装完之后确实没让人失望——它不是一个传统意义上的插件，也不是一个新的 CLI 工具，而是一整套 Skill 技能包，能让 Codex CLI 这类编程助手从“听话的实习生”变成“能独立拆解任务的老手”。简单说，它解决的问题非常具体：默认状态下的 AI 编程助手，你让它改个需求，它可能直接把整个文件重写了；你让它跑个测试，它能给你编出十种不跑的借口。而 superpowers 做的事情，就是把 AI 的行为方式重新“调教”一遍，让它有规划、有节奏、有检查机制地干活。

这篇文章我不打算只讲安装命令，而是把 superpowers 的底层逻辑、和其他 Skill 体系的关系、在不同环境（Codex CLI、Workbuddy、Trae Work）里的配置差异，以及我实际踩过的坑都梳理清楚。适合正在用或准备用 AI 编程助手的开发者，尤其是对 Codex CLI 感兴趣、想进一步提升 AI 输出质量的人。文章偏实操，我会尽量把每一步都写明白。

1. 到底什么是 superpowers——从“AI 的能力需要结构化管理”说起

很多人在第一次听说 Skill 的时候会有一个误解：以为 Skill 是给 AI 增加“云端能力”，装上之后 AI 就能访问更多数据、调用更强大的模型。其实完全不是。Skill 的核心作用，是给 AI 提供一套结构化的“工作方法和行为约束”，它改变的不是模型本身的能力上限，而是模型在当前任务里的输出质量下限。

1.1 它不是“云能力”，是一套可复用的技能包

我打个比方。同样一个资深工程师，你直接丢给他一个需求让他写代码，和他拿着你们团队沉淀的《编码规范》《代码评审清单》《重构流程手册》再动手，产出的东西是完全不一样的。superpowers 之于 Codex，就相当于那套沉淀好的《工程师工作手册》。

从 GitHub 仓库的结构上也能看出来，superpowers 的 skill 分成几大类：有脑暴（brainstorming）类，让 AI 在动手写代码之前先和你把需求对清楚；有规划（planning）类，把一个大任务拆成可以逐步交付的小步骤；有执行（execution）类，比如编写代码、运行测试、修复错误；还有复盘（retrospective）类，让 AI 做完一件事之后自己总结经验，为下一轮工作做准备。这套结构不是随便拍的，它对应的是一个人真正在写代码时的工作状态：先想清楚为什么做、再拆解怎么做、然后动手做、做完再回头看。

在 AI Agent 的圈子里，这套东西通常被称为“技能（Skill）”，而 superpowers 是最早把整套软件开发流程做成 Skill 体系开源出来的项目之一。它的设计哲学是：不要试图让 AI 一步到位地写出完美代码，而是给它搭一条流水线，让它在流水线的每个环节都用最正确的方式工作。这也是我后来在 Codex 里越用越顺手的核心原因——AI 不再是“一步到位瞎写”，而是“分步推进稳做”。

1.2 为什么我用了一圈最后还是保留了它

说实话，今年我试过的 Skill 框架不少，各有各的思路：有的偏向代码安全审计，有的偏向测试生成，有的偏向文档编写。superpowers 最大的区别在于它把“行为管理”做成了体系，而不是孤立的几个技巧。

我用一个很典型的例子来说明。以前直接用 Codex 写一个小工具，我的指令是“帮我写一个批量重命名文件的 Python 脚本”。Codex 会很快给我生成一段能跑的代码，但往往没有错误处理、没有日志、没有边界检查。而装上 superpowers 之后，如果它的规划 skill 被激活，Codex 会反过来问我几个问题：你希望用正则匹配还是精确匹配？覆盖式重命名还是先预览一遍？需要保留原文件名映射表吗？如果你确认了这些信息，它才真正开始写。写完之后，它还会主动提出要不要跑一遍测试，或者做一次代码审查。这体验完全不一样。

所以 superpowers 的定位很清晰：它不是给你增加“魔法”，而是给 AI 装上一套自我管理机制，让它的每一步都可解释、可追溯、可验证。对开发团队来说，这意味着 AI 生成的代码不再是“黑盒产物”，而是可评审、可维护的工程产物。对一个独立开发者来说，这意味着你可以把更多琐碎的编码任务放心地交给 AI 去干，自己专注在架构和关键决策上。

在我目前的日常开发流里，superpowers 已经是 Codex CLI 环境的标配了，而且我也把同一套 skill 配置同步到了 Workbuddy 和 Trae Work 里，这样无论我在哪个编辑器环境下工作，AI 助手的行为都是统一的。

2. 核心机制拆解：skill 文件、引导词与技能链

如果你只是想把 superpowers 装上然后用起来，可以直接跳到第 3 节。但我觉得还是有必要花点时间讲清楚它内部到底是怎么运作的，因为这决定了你会不会用，以及能不能自己扩展它。

2.1 每一个 skill 都是“流程 + 清单 + 范例”

superpowers 里的每一个技能，在仓库里其实就是一个目录，目录里面通常包含一个SKILL.md文件，有的还有额外的参考文档或模板。这个文件的内容是 Markdown 格式，核心结构是这样的：

• 技能描述（description）：告诉 AI 这个技能在什么场景下使用，它服务的任务类型是什么。
• 执行流程（workflow）：把做这件事的步骤拆开，比如“先收集需求 -> 再制定方案 -> 再写代码 -> 最后自测”。
• 检查清单（checklist）：在做完关键动作后逐项确认，相当于给 AI 设定一个“飞行前的检查单”。
• 范例（examples）：给出一段理想的输入输出，让 AI 理解“做得好”的标准到底是什么。

我拆开来看一下。以它内置的“写代码”类技能为例（不同分支可能命名略有差异），SKILL.md 里会强调：在真正开始写之前，先确认已经理解了需求；代码要符合当前项目的风格；关键逻辑必须有注释；实现完成后要主动提出测试方案。这些看起来是“天然的常识”，但对大语言模型来说，如果没有明确的文本指令，它并不会每次都自动遵守。Skill 的作用就是用确定性的文本，去对冲模型输出的不确定性。

这和提示词工程（Prompt Engineering）是一脉相承的，但 Skill 做得更工程化：它把提示词拆散成可插拔的模块，你不需要在每次对话里都重复写一大段规则，只要让 AI 在合适的时机读取对应的 SKILL.md 文件就行了。从这个角度理解，superpowers 本质上是“一套标准化的提示词管理方案”。

2.2 superpowers 的技能链是如何串联的

我刚接触的时候有个困惑：superpowers 提供了这么多技能，AI 怎么知道在哪个阶段调用哪一个？后来我把整个 skill 体系理了一遍，发现它其实有一条清晰的“技能链”，对应一个完整软件的研发周期。

拿一个典型任务举例。当你对 Codex 说“帮我优化一下登录模块的性能”，如果 superpowers 的会话引导技能被激活，Codex 不会马上动手改代码，而会先进入“需求澄清”环节。确认完需求之后，它会进入“任务分解”环节，把性能优化拆成：分析瓶颈、设计优化方案、实施修改、回归测试几个子任务。在编码阶段，它调用“编码规范”相关技能来约束代码风格。写完代码后，它会进入“质量检查”环节，主动检查边界条件，甚至尝试跑测试。

这套串联机制，靠的是 SKILL.md 文件里的“触发条件”。每个技能文件里都会写清楚：当什么情况出现时，你应该读取并使用这个技能。Codex 的 Agent 循环会判断当前的环境状态，去匹配最适合的技能。所以你在使用的时候并不需要手动去切换技能，而是通过任务描述本身，让 AI 自动激活对应的流程。

2.3 自己在什么时候“喂”它自定义技能

superpowers 的价值不只是开箱即用，更在于它是一个可扩展的框架。我们团队在后端项目里加了两个自定义技能：一个是“数据库迁移规范”，另一个是“API 错误码约定”。做法很简单，仿照仓库里已有的技能结构，建一个目录，里面写一个 SKILL.md，描述清楚触发场景和执行步骤，然后在 Codex 的配置里把 skills 路径指向我们自己的目录就行了。

这样做的意义在于：团队的知识沉淀不再只存在于 Wiki 里，而是变成了 AI 可以直接读取并执行的活文档。写代码时，AI 会自觉遵守团队的数据库变更规范；返回错误时，AI 会按约定的错误码格式来组织响应。哪怕是一个刚入职的新人，只要他使用这套开发环境，写出来的代码也基本能符合团队规范。这就是 Skill 体系在生产环境里最有价值的应用场景。

3. 实操：在 Codex CLI 安装并激活 superpowers

前面讲了那么多原理，接下来直接上实操。我在安装过程中试过几种不同的方式，也遇到过先装后失效的情况，这里把最稳妥的路径完整走一遍。

3.1 环境准备

在安装前，先把环境梳理清楚。superpowers 本质上是给 Codex 这类 CLI Agent 使用的 Skill 集合，所以你本机得先有 Codex CLI 环境，并且能正常调用模型。

需要确认的环境可以看一下这个表格：

在开始之前，最好先跑一次codex --version确认版本号没问题。如果你是第一次安装 Codex CLI，直接用官方推荐的安装方式就好，我这里不赘述，但有一个小提醒：装好之后一定要先把某个小 demo 跑通，确认 AI 能正常回复，再继续下一步装 superpowers。我见过太多人直接从安装 superpowers 开始，装了半小时发现是 Codex 本身没配好，全白忙活。

3.2 Windows 用户：建议换到 WSL 环境再动手

superpowers 官方文档里的安装命令几乎都是 Unix shell 风格，所以 Windows 用户如果直接在 PowerShell 或 CMD 里跑，大概率会遇到路径问题。我自己实测下来，最省事的方式是在 WSL（Windows Subsystem for Linux）里安装和运行 Codex CLI。

WSL 的好处有几点：

• 文件路径遵循 Linux 规范，和官方文档里的示例完全一致。
• 脚本执行不会因为权限或路径分隔符问题卡壳。
• 后续如果要扩展 skill 或用 Git 管理配置文件，体验都更顺。

如果你不想用 WSL，那至少装一个 Git Bash，然后用它来执行安装命令，也可以救急。但从稳定性角度，我还是推荐 WSL，尤其你是重度 Codex 用户的话，这个投入非常值得。

注意：这里说的 WSL 只是日常开发环境的建议，不涉及任何特殊网络配置。VSCode 对 WSL 的支持已经很完善，你在 Windows 里写代码、在 WSL 里跑 Agent，完全无缝衔接。

3.3 安装步骤全记录

下面是在 macOS / Linux（含 WSL）环境下，我从零到一安装 superpowers 的完整过程。

第一步，克隆仓库到本地的一个固定目录。我习惯把这类工具统一放在~/workspace/tools/下面，避免散落到用户的根目录：

mkdir -p ~/workspace/tools cd ~/workspace/tools git clone https://github.com/obra/superpowers.git

克隆完成之后，检查一下目录结构：

ls -la ~/workspace/tools/superpowers

正常情况下，你会看到一个skills目录，里面放着所有技能子目录。这是关键路径，后面配置时要用到。

第二步，确认 Codex CLI 能识别到这个技能目录。不同版本的 Codex CLI 配置方式略有差异，但核心路径配置逻辑是一致的——它会在你的用户配置目录下寻找包含 skill 的路径。以当前的主流版本为例，Codex CLI 会读取~/.codex/config.toml（这个配置文件可以由codex初始化命令自动生成）。我们需要在配置里指认“额外的技能目录”：

[experimental] skill_paths = [ "/你的用户目录/workspace/tools/superpowers/skills" ]

注意把这里的具体路径替换成你自己的真实路径。如果skill_paths这个配置项在你看的文档里存在，那直接用；如果版本提示字段不正确，可以走下面的软链接方案：

mkdir -p ~/.codex/skills ln -s ~/workspace/tools/superpowers/skills/* ~/.codex/skills/

第三步，重启 Codex CLI 会话。这一步很容易被忽略，但非常重要。Codex 只在启动时加载一次技能配置，如果你是在已经打开的会话里修改的配置，不重启根本不会生效。

第四步，验证技能是否被加载。打开一个新的 Codex 会话，先问一个简单的技能相关问题，或者直接查看会话的日志输出。能确认的方法有两个：一是看启动日志里有没有类似loading skills from ...的信息，二是在对话里让 AI 自己描述一下“你有哪些可用技能”。如果 AI 能讲出 superpowers 里特有的技能名和行为规范，说明加载成功了。

提示：不要在安装阶段直接丢一个大型开发任务去测，效果会受网络和模型波动影响，不好判断是配置问题还是任务本身的问题。先做小验证，确认技能已加载，再上真实任务。

3.4 验证安装后的第一个测试：让技能真正跑起来

安装完成后，我最常用的一行测试指令是：

请使用你掌握的最佳实践，帮我设计并实现一个小工具，功能是从一组 Markdown 文件中提取所有的一二级标题，并生成目录索引。

注意，这句话重点在“最佳实践”。如果 superpowers 已生效，Codex 会先跟你确认细节，比如输出的目录格式、是否包含文件路径、是否跳过特定目录等，然后给出一个实施计划，最后才动笔写代码。它写的代码里会有错误处理，会包含测试建议，而不是被蹦出来一个光秃秃的函数。

我第一次测试时，它真的先问了四个问题才动手，我一开始觉得“怎么这么啰嗦”，后来才意识到这正是 superpowers 的价值——在动手前把需求和边界确认清楚，比事后返工高效得多。

4. 进阶配置：Workbuddy 和 Trae Work 里的差异与坑

Codex CLI 只是 superpowers 的一个运行环境。随着 Skill 体系流行起来，很多 AI 编程工具都开始兼容这套规范，比如 Workbuddy 和 Trae Work（前面热词里也出现了）。我也把 superpowers 同步到了这两个环境里，整理一下配置差异和各自容易踩的坑。

4.1 Workbuddy 安装 Skill 的正确姿势

Workbuddy 对 Skill 的支持逻辑和 Codex 类似，也是扫描指定目录里的 SKILL.md 文件，注入到对话上下文中。但因为 Workbuddy 是 IDE 插件形态，它的配置入口藏在插件设置里，比命令行工具要隐蔽一些。

我实际安装时用的是它的 CLI 辅助路径：先确保 workbuddy 能识别到用户级目录下的 skills 文件夹，然后把 superpowers 的 skills 目录软链接过去。如果你是 macOS 用户，重点检查~/Library/Application Support/Workbuddy/下面有没有可识别的 skills 目录；Windows 则去查%APPDATA%\Workbuddy\。不同版本路径名可能有差异，最稳的办法是在设置面板里搜skill，看它有没有暴露路径字段。

这里有一个和 Codex 不一样的地方：Workbuddy 的技能加载粒度更细，它会要求每个技能目录下必须有一个完整的 SKILL.md，如果缺少元信息，这个技能会被静默忽略，而且不报错。所以如果你在 Workbuddy 里发现某些能力没生效，先别急着怀疑 superpowers，很可能只是某个技能的元信息不兼容。

4.2 Trae Work 里的一个坑：技能路径别乱放

Trae Work 是国内团队出品的 AI 编程环境，配置上整体很友好，默认会扫描工作区下的.trae/skills目录。如果你想全局使用 superpowers，而不是只在某个项目里用，就需要在用户目录的 settings 里设置trae.skills.extraPaths。

我在这里踩过一个具体问题：最初我想把 superpowers 的 skills 目录直接放到工作区某个项目的.trae/skills下，发现只有那个项目能识别，换一个项目就全失效了。后来改成在用户级配置里声明全局路径，问题才彻底解决。

建议的做法是，在 Trae Work 的 settings.json 里加这样一段：

{ "trae.skills.extraPaths": [ "/你的绝对路径/superpowers/skills" ] }

配置好之后，同样记得重启 Trae Work，让它重新加载技能索引。如果你同时开着多个项目，最好把 Trae Work 重启干净，避免索引没刷新导致技能“时灵时不灵”。

4.3 多环境共用一套 superpowers

如果你和我一样，在 Codex CLI、Workbuddy、Trae Work 三个环境里都要用，就不用把仓库复制三份了。做法是：本地只保留一份 superpowers 仓库，其他几个环境通过配置或者软链接指向同一份文件。这样后续升级知识库时，只需git pull一次，全局生效，维护成本最低。

不过多环境共用一个技能目录也有一个细节要注意：不同工具对技能文件里 frontmatter（YAML 元信息）的解析规则并不完全一致，有些工具要求有描述字段，有些则要求有触发词。如果你在 A 环境里能用、在 B 环境里失效，大概率就是这个原因。我的经验是尽量保持元信息完整，把 description、当触发场景、示例字段都写全，这样兼容性最好。如果遇到个别工具还是识别不了，就在该工具里建一个本地 override 目录，只放需要额外适配的那几个技能。

5. 扩展与自定义：把 superpowers 变成你自己的武器库

superpowers 是一个开源框架，不是一套固化的流程，所以你在掌握用法之后完全可以往里面填自己的东西。这一节我讲讲如何给 superpowers 添加自定义技能，以及我在实际项目中是怎么扩展的。

5.1 自定义技能的结构范例

新增一个技能非常简单，就是创建一个目录和一份 Markdown 文件。目录名就是技能名，SKILL.md 是技能核心。我以一个“代码提交信息规范”技能为例，展示一下 SKILL.md 里的关键要素：

--- name: commit-message-standard description: 当 AI 准备生成 git commit message 时使用，确保提交信息符合团队的 Conventional Commits 规范。 --- ## 触发时机 - 用户要求提交代码 - AI 完成一段代码修改后准备总结变更 - 用户要求改写或优化现有提交信息 ## 执行流程 1. 查看当前项目的 git diff，了解变更类型。 2. 根据 diff 确定是 feat、fix、docs、refactor、test 中的哪一类。 3. 写出格式为 `<type>(<scope>): <description>` 的提交信息。 4. 如果涉及破坏性变更，追加 BREAKING CHANGE 段落。 ## 检查清单 - [ ] commit message 是英文还是中文？按团队惯例执行。 - [ ] 是否包含关联的 issue 编号？ - [ ] 描述是否简洁、避免无意义词汇？ ## 示例 feat(auth): 增加基于短信验证码的登录方式 - 新增发送验证码接口 - 新增验证码校验逻辑 - 补充单元测试 Closes #1024

以后只要 AI 准备生成 commit message，它就会先读这一份规范，按照团队约定来写。这个能力不是来自更强的模型，而是来自一套“情景化的工作标准”，也就是 Skill 的价值。

5.2 我实际加的 3 个小技能

在项目实践中，我往里加了几个更垂直的技能，这里挑三个有代表性的讲一下。

第一个是“安全审查技能”。在我们做支付相关的模块时，我建了一个 security-review 技能，里面列出了常见漏洞清单，比如 SQL 注入、越权、敏感信息硬编码、日志泄漏等。AI 在写完代码后会自动按这个清单做一轮自审，能堵住不少低级的疏漏。

第二个是“架构一致性检查”。我们有个项目历史悠久，个别模块目录结构比较混乱。我把理想目录规范写进技能里，要求 AI 在增加新文件时先检查目录是否符合规范，不符合就提示重构建议。这听起来不起眼，但在多人协作的项目里，它能明显减少代码仓库“越摊越乱”的速度。

第三个是“交接文档生成”。我们团队规定 AI 完成一个较大的任务后，必须输出一份交接文档，包括变更背景、改动文件、测试结果、潜在风险。这个技能很大程度改善了 AI 产出的可读性，也让代码评审的效率提升了一个档次。

5.3 版本管理与升级注意

superpowers 本身迭代也很快，所以升级时要注意几个点。第一，升级前先看改动日志，别盲目的git pull，有时候新版本会调整技能目录结构或触发方式，导致你之前自定义的技能失效。第二，如果你在本地 fork 了仓库并加了大量自定义技能，升级时优先用git fetch+git rebase，减少合并冲突。第三，升级后必须在新会话里测试，旧会话不会自动加载变更后的技能定义。

我自己吃过一次亏：有一次直接git pull，结果冲突把本地改过的 SKILL.md 覆盖了，后来发现所有 AI 都不遵守自定义规范，排查了半天才发现问题。所以现在我的习惯是，fork 一份自己的仓库，superpowers 的上游代码放在 remote upstream，升级时先看 diff，再去合并。

6. 常见问题与排查经验实录

这节集中回答我在安装和使用 superpowers 过程中遇到的典型问题。很多问题你搜官方文档都不一定有答案，纯靠实际操作踩坑总结，所以值得重点看一下。

6.1 症状速查表

6.2 两次真实的故障排查过程

我第一次装完 superpowers 后，在 Codex 里怎么测都感觉 AI 没什么变化，它还是像以前那样不假思索地直接写代码。我当时差点怀疑这项目是个“PPT 项目”。后来排查了半天，发现我配置skill_paths的路径时手滑多加了一个字符，目录不存在，Codex 静默忽略了它，压根没报错。所以如果你装了没效果，第一件事永远是确认路径有没有写对，而不是去研究技能内容。

第二次是在 Workbuddy 里，技能列表里能看见内容，但实际问题是被另一个同类型的本地技能“抢先”匹配了。在 Workbuddy 这种插件环境里，它会把自己的技能和自定义技能合并成一个池子，如果有多个技能描述相似，AI 可能会选错优先级。解决办法是给不常用或优先级低的技能改名为zz-前缀开头，相当于把它们的匹配顺序往后压。

这个教训就是：技能并不仅仅是加载就行，还要管理好优先级和命名，尤其是在同时使用多个技能包的时候。

6.3 几个独家避坑心得

最后聊几个我在实战中总结出来的心得，这些是常规文档里不会写的内容。

第一，技能不是越多越好。我把十几个技能全部开着的阶段，Codex 的响应速度明显变慢，而且它经常在多个技能之间“反复横跳”。后来我精简到六个核心技能，效果反而更稳定。技能的本质是“上下文约束”，一次塞太多规则，模型会不知所措。

第二，用一段时间后要注意垃圾技能堆积。有些技能你可能只是临时用一次，之后再也用不上，但它们仍然会在每次会话里被扫描、被载入。建议每隔一段时间就清理一次不常用的技能目录，保持整个技能库干净。

第三，如果你发现 superpowers 在某些任务上让你觉得“太啰嗦”、总是先问一堆问题，不用担心，那是它的设计。你可以在指令里明确说“这次不要额外确认，直接做”，AI 就会跳过中间的澄清步骤，直接进入执行。换句话说，技能不是束缚，更像是一套默认的安全策略，你有权在任何时候手动退出。

第四，建议把技能配置纳入版本管理，无论是个人项目还是团队项目。我自己的做法是把.codex/和技能目录都放进 Git 仓库，这样每次环境出问题，都能快速把配置恢复到稳定状态。对于团队协作来说，这也能保证所有人都用同一套“AI 工作标准”。

写在最后的体会

做了一段时间的 AI 辅助编程之后，我的一个核心体会是：大模型本身的能力其实差别没那么大，真正拉开体验差距的，是你有没有给它搭一套优秀的工作框架。superpowers 最打动我的地方就是它把“怎样才能写好代码”这件事拆成了可执行的流程和清单，让 AI 从“会说话的代码生成器”变成了“有章法的编码搭档”。

如果你之前一直觉得 Codex 写代码虽然快但不够“稳”，我强烈建议你去试试 superpowers。安装方式在 GitHub 上很清晰，学习曲线也不陡峭，花一个下午搞明白技能机制，之后每天开发效率的提升都是看得见的。如果你在用的过程中发现了一些有意思的自定义玩法，也可以顺着这套思路自己去扩展技能，那才是真正让 superpowers 变成“你的超能力”的时刻。