企业官网建设流程全解析

最近代码圈里有个词出现得特别频繁——“superpowers”。打开各种开发社区，满屏都是“superpowers 使用教程”“Codex CLI 安装 superpowers”“Trae 安装 superpowers skill”这类搜索词。第一次看到的时候我也挺懵，以为是什么新出的游戏模组或者效率工具。后来在自己项目里跑通一遍才发现，它其实是冲着 AI 编程助手“只会聊不会干”那个老大难问题来的。

如果你手头正在用 Codex CLI、Trae 这类 AI 编程工具，又总觉得它们平时只能帮你写点零散代码、改几个报错，稍微复杂一点的任务就开始自由发挥、甚至反复横跳，那这篇东西值得你花十分钟看完。我会从“superpowers 到底解决什么问题”讲起，把它在 Codex CLI 和 Trae 两个环境里的安装过程、配置逻辑、常用工作流都铺开，最后再聊聊我在实战里踩过的几个坑和目前觉得最稳的用法。

1. 先说清楚 superpowers 是什么：它不是工具，是一套“技能栈”

很多人第一反应是去 GitHub 搜 “superpowers”，看到一个仓库就以为是某个 CLI 工具，拿到手之后反而不知道怎么用。其实 superpowers 更像一个“技能包”或者“工作流定义层”。它本身不直接生成代码，而是给 AI 编程助手提供一套可执行、可复用的任务流程。

1.1 为什么编码助手会“懂很多但做不成事”

用过 Codex CLI 这类工具的人应该都有体会：你让它写个排序算法，它写得又快又对；你让它“重构整个模块”，它就开始发挥想象力了。不是模型变笨了，而是它缺乏一个明确的“做事方法”。写排序算法这件事，人类程序员早就形成肌肉记忆了，模型也见过无数遍，自然不需要额外引导。但“重构模块”这种任务牵扯到读代码、找依赖、改接口、跑测试、看回归，每一步都该怎么做，模型心里其实没底，只能靠猜。

大多数人的解决办法是在提示词里拼命描述步骤——“你先读一下这几个文件，然后画个依赖图，再列计划，最后动手改”。这么做有效，但非常累。而且每个人的提示词风格不一样，这次写得好下次不一定记得住，换个人来写又完全是另一种风格。

superpowers 的思路是：把这类复杂任务拆成一套标准化的“技能”，每个技能都有自己的说明文件、示例、脚本和工作流。AI 助手只要加载了这些技能，就相当于脑子里多了一套“操作手册”，遇到对应任务时能按手册一步步来，而不是现场乱编。

1.2 技能栈的基础结构：SKILL.md 与配套资源

superpowers 底层的技术形态，是我个人很喜欢的一种设计——“以文档为中心的技能包”。一个技能本质上就是一个目录，目录里最关键的文件是SKILL.md，它用结构化格式描述了这个技能是干什么的、在什么场景下触发、具体需要执行哪些步骤。旁边可能还会放scripts/、examples/、reference/这些子目录，用来承载更详细的辅助材料。

打个比方，这就像你给一个新同事写了一份“入职手册”：手册第一页写明他的岗位职责，后面几页是流程图、常用命令、范例代码。AI 助手看到那份手册之后，就知道什么时候该调用什么能力、按什么顺序执行。

这套结构的好处是极度透明。普通提示词是藏在对话里的，黑盒一样；技能则是显式存放在项目目录或者全局目录里的文档，你随时能打开看它到底写了什么、引导模型做了什么。版本管理也很方便，一个技能文件夹直接丢进 Git 仓库就行，团队协作时大家用的是同一套“手册”。

1.3 superpowers 真正带来的改变：从“生成代码”到“执行任务”

我自己用了两周之后的感受是：安装 superpowers 之前，Codex CLI 像一个很聪明但没什么耐心的实习生，你说一步它做一步，不问清楚就瞎猜；安装之后，它更像一个带过几个项目的熟手，拿到任务会先梳理范围，再制定计划，执行过程中还会自己验证结果。

这个改变不是说模型变强了，而是“流程约束”起作用了。比如代码审查这个场景，没有技能时，AI 会笼统地扫一遍代码，给几条通用建议；加载了代码审查技能之后，它会按照“先看变更范围→检查测试覆盖→找潜在边界问题→给出按严重程度排序的修改意见”这套流程走，输出的质量稳定很多，不会再出现那种“这个文件写得很好，没有发现问题”之类的敷衍结论。

如果你能接受“AI 编程助手不该只是聊天机器人，而应该是有方法论的执行者”这个前提，那 superpowers 就非常对你的胃口。

2. 安装前必须理解的体系结构：四个层级别搞混

很多人在安装 superpowers 时翻车，不是操作有多难，而是没搞清楚它到底装在哪一层。这里我先画个简单的分层逻辑，后面所有安装步骤都是围绕这几层展开的。

2.1 第一层：运行时（Runtime）

运行时就是承载 AI 助手的那个程序，比如 Codex CLI、Trae、Claude Code 等等。技能不是独立运行的，它必须寄生在某个运行时里，通过运行时去读取、解析、执行。你没法“单独运行”一个技能，就像你没法不通过浏览器就打开一个网页。所以安装 superpowers 的第一步，永远是先确认自己手头有一款支持技能机制的 AI 编程工具。

2.2 第二层：技能加载路径

运行时需要知道去哪里找技能。常见的做法有两种：一种是放到全局目录（比如~/.codex/skills/），所有项目都能用；另一种是放到项目目录（比如.codex/skills/），只对当前仓库生效。这个选择会影响后面的一堆配置，我建议个人开发用全局目录，团队协作用项目目录，这个后面细说。

2.3 第三层：技能描述与执行逻辑

这一层是 superpowers 的核心，也就是那些技能文件夹里的内容。前面提到的SKILL.md就是这一层的代表。运行时加载技能时，实际上是在读这份描述文件，然后把里面的步骤塞进模型的上下文。技能好不好用，70% 取决于这份文件写得好不好。

2.4 第四层：触发机制

最后一步是触发。技能怎么被“唤醒”？有些技能是用户显式要求的，比如你在对话里直接说“用 git 工作流技能帮我处理这次提交”；有些则是运行时根据对话内容自动判断的，比如你让 AI 修一个 bug，它发现自己的技能列表里有“调试技能”，就会自动加载。

理解这四层之后，你再去看那些安装教程就不会晕了。网上很多教程喜欢直接甩命令，看起来很简单，但它没说清楚这些文件该放在哪一层、为什么放那里。一旦目录错位，技能加载不上，你连排查的头绪都没有。

3. Codex CLI 安装 superpowers：两条路径我都实际跑过

Codex CLI 是 OpenAI 的命令行编程工具，也是社区里对 superpowers 支持比较早、比较完整的运行时之一。安装方式不复杂，但有不少细节值得注意。

3.1 前置准备：确认 Codex CLI 版本与环境依赖

动手之前先做两件小事。第一，确认你的 Codex CLI 版本不是太老，至少是支持技能目录的版本。第二，确认你本机装了 Git，因为后面拉取技能包要用。

这一步很容易被忽略，很多人装了半天，发现技能一直加载不上，最后查来查去是 Codex CLI 版本太旧，压根不认skills目录。建议直接升级到最新版再开始：

npm install -g @openai/codex codex --version

如果之前安装过其他 AI 编程工具，记住不要跟 Codex CLI 的全局目录搞混，它的配置目录通常是~/.codex/。

3.2 路径 A：全局安装，所有项目通用

全局安装适合你自己个人电脑，装一次之后不管开哪个项目都能用。操作方法很直白：把 superpowers 仓库克隆到 Codex 的全局技能目录里。

mkdir -p ~/.codex/skills git clone https://github.com/obra/superpowers.git ~/.codex/skills/superpowers

克隆完成之后，检查一下目录结构，确认SKILL.md确实在~/.codex/skills/superpowers/下面，而不是多套了一层目录。

接下来是让 Codex CLI 知道技能的存在。这一步取决于你的 Codex CLI 版本：老一点的版本会要求你在配置文件里显式声明技能目录路径，新一点的版本则会自动扫描默认的技能目录。我建议在AGENTS.md文件里加一段说明，这样最稳，不管哪个版本都认：

在开始任何任务之前，检查 ~/.codex/skills/ 下是否有与当前任务相关的技能。 如果有，请先阅读对应技能目录下的 SKILL.md，然后严格按照技能描述的工作流执行。

AGENTS.md是 Codex 这类工具的项目级行为说明文件，放在项目根目录即可。它的作用就像给 AI 立规矩——先看技能库再干活，别上来就直接写代码。

3.3 路径 B：项目级安装，团队协作更可控

团队项目不建议把技能放到个人全局目录里，因为每个人电脑上都有各自的版本，一旦更新不同步，行为就千奇百怪。更好的做法是把技能直接放进项目仓库：

mkdir -p .codex/skills git clone https://github.com/obra/superpowers.git .codex/skills/superpowers rm -rf .codex/skills/superpowers/.git

注意最后一条命令，复制完之后要把技能目录里的.git删掉，否则会变成一个嵌套的 Git 仓库，之后提交项目代码时会出现一堆乱七八糟的子模块提示。

然后同样在项目根目录的AGENTS.md里声明技能路径：

优先读取 .codex/skills/ 目录中的技能文件，按照其中定义的工作流执行任务。

项目级安装的好处有两个：一是所有人用同一份技能，行为一致；二是技能随着代码仓库一起走，Code Review 的时候技能变更也能被看到，不会有“我这跑得好好的，怎么你那边就不行”的扯皮。

3.4 启动 Codex 验证技能是否被加载

安装完先别急着跑复杂任务。启动一个干净的 Codex 会话，输入一句验证指令，比如“列出你当前可用的技能，并简要说明每个技能的用途”。如果配置正确，它会像报菜名一样给你列出一串技能及对应描述，说明加载成功。如果它说“当前没有可用技能”或者干脆不知道你在说什么，基本就是目录放错或者AGENTS.md没生效，回头检查路径即可。

第一次加载技能时，Codex 会把技能内容读进上下文，这个过程会消耗一些 token。这是正常的，不用慌。后续同一个会话里再次使用技能时，模型通常已经“记住”了一部分，不会每次全部重读。

4. Trae 里的 superpowers 安装：和 Codex 的两个核心差异

Trae 是一款自带 AI 能力的编辑器，国内用户用得也不少。它的技能机制跟 Codex CLI 不太一样，如果你只会 Codex 那套，到 Trae 里就很容易找不到北。

4.1 差异一：Trae 更依赖图形界面，但底层仍是技能目录

Codex 是纯命令行工具，安装技能主要是敲命令、改配置文件。Trae 是 IDE，绝大部分操作在图形界面里完成，但底层依然离不开“技能目录”这个概念。

打开 Trae 的设置面板，找到 Skills（技能）相关入口，你会看到它支持从本地目录导入技能，也支持从市场安装。如果你已经从 GitHub 拉下来了 superpowers 仓库，那就选“从本地导入”，直接把superpowers目录拖进去即可。如果你还没下载，也可以在 Trae 的界面里直接填仓库地址，让它帮你拉取。

这里要特别注意的是，Trae 国内版和国际版的界面文字略有差异，但功能入口基本一致，都叫“技能”或“Skills”。如果你没找到这个入口，检查一下 Trae 是不是需要登录账号才能解锁技能功能，不少 AI IDE 把技能管理做成了账号功能，不登录的话那一栏直接隐藏。

4.2 差异二：项目级技能目录的约定不同

Trae 的项目级技能目录约定跟 Codex 不一样。Codex 习惯用.codex/skills/，Trae 则倾向于识别项目根目录下的.trae/skills/。所以你在 GitHub 上克隆 superpowers 之后，在 Trae 项目里使用之前，通常需要复制一份到 Trae 的技能目录：

mkdir -p .trae/skills cp -r superpowers .trae/skills/

多嘴一句，不要把同一个技能同时放在全局和项目两个位置，Trae 加载时可能会冲突。我的建议是：如果是自己的临时项目，全局即可；如果是多人协作的正式项目，放.trae/skills/并提交到 Git。

4.3 Trae 里调用技能的两种方式

在 Trae 里，技能触发比命令行工具更“松弛”一些。第一种方式是手动触发，你在对话框里直接描述需求，同时加上一句“请使用 superpowers 中的 XXX 技能来完成”。第二种方式是自动匹配，Trae 会根据你的问题内容自动推荐或加载相关技能，界面里会显示当前会话正在使用哪些技能。

我个人的体验是：自动匹配方便但不够稳定，有时候我明明想要代码审查，它却去加载了调试技能。所以关键时刻还是手动指定更靠谱。就像导航软件给你推荐了一条路，但你真的赶时间的话，还是得自己提前说清目的地。

4.4 Trae 装完不生效，多半是缓存问题

Trae 作为一款桌面应用，对技能目录的扫描不是即时的。你刚把 superpowers 放进去，马上开一个新会话测试，很可能会发现 AI 根本不知道有这个技能存在。这不是你装错了，而是缓存没刷新。

解决办法简单粗暴：重启 Trae。重启之后它才会重新扫描技能目录，把新技能加载进来。如果重启还不行，那就去设置里找“清除缓存”之类的按钮，清完再重启。我在公司电脑上遇到过几次这种怪问题，基本都是靠重启解决的，没遇到需要重装的情况。

5. 真正值钱的是工作流：superpowers 里的技能到底怎么用

很多教程装完 superpowers 之后就戛然而止，告诉你“装好了，去用吧”。但真正上手的时候反而傻眼——技能那么多，到底该让 AI 用哪个？怎么组合？这里我挑三个我在日常开发里用得最频繁的工作流，说说它们是怎么运转的。

5.1 工作流一：从模糊需求到测试驱动实现

以前让 AI 写功能，它拿到一句话需求就直接开写，写出来的东西经常跑不通，或者功能实现有偏差。superpowers 会引导它先进入“计划模式”，把需求拆成可验证的小任务，甚至主动要求你补充边界条件。

我自己实测的过程大概是这样的。我说“帮我实现一个带过期时间的缓存”，它的响应不再是立刻写代码，而是先说：我理解你的需求是要一个支持 TTL 的键值缓存，我准备先用 TDD 方式实现：第一步先定义接口，第二步写过期判断的测试，第三步实现底层存储，第四步跑测试确认。整个过程它会一步步做给我看，每完成一步还会停下来问我要不要继续。这种体验接近带一个初级开发，而不是面对一个只会吐代码的机器。

5.2 工作流二：调试问题时的“医生模式”

AI 最大的毛病之一就是喜欢猜错误原因。你给它一个报错信息，它不先查证据就直接开药方。superpowers 的调试技能会把流程改成：复现问题 → 收集上下文 → 定位根因 → 提出修复方案 → 验证修复效果。

有一次我的 Node 服务线上偶发内存泄漏，光靠日志很难定位。我让 Codex CLI 用调试技能来分析，它没有立刻给我甩一个“可能是全局变量没清理”的结论，而是让我先提供 Heap 快照，再对比不同时间点的内存变化。顺着这套流程，我们最终定位到一个第三方库缓存了大型对象导致的问题。整个过程它的分析节奏很扎实，没有乱跳步。

5.3 工作流三：代码审查从走过场变成仔细过

代码审查这个场景其实是最容易体现 superpowers 价值的。不用技能的时候，AI 审查代码是“通读一遍→说几句好话→给两个不痛不痒的建议”。用了 code review 技能之后，它会先分析这次变更涉及哪些文件、改了什么逻辑，再逐个文件检查测试覆盖、错误处理、边界条件，最后才输出一份按优先级排序的 review 意见。

我特别留意到一点：它会在意见里标注“建议修改”“需要讨论”“可选优化”三个级别。不会像以前那样把所有问题混在一起，导致我看的时候不知道该先处理哪个。这个小细节对团队协作很重要，毕竟大家在 review 时时间都有限，按优先级处理效率高很多。

5.4 组合使用：把技能连成一条流水线

单个技能是“招式”，连起来才是“套路”。我目前在个人项目里有一套固定组合流程：需求进来之后，先用计划技能拆分任务，然后把拆分结果交给 TDD 技能去实现，写完代码用审查技能过一遍，最后用 Git 技能生成规范的提交信息。

这一套流程顺手之后，我发现自己从“事无巨细地写提示词”里解放出来了。以前每次开新需求都得重新描述一遍流程，现在只需要说清楚需求本身，AI 自己会按技能库里的“手册”走。那种感觉就像从手动挡换成了自动挡。

6. 实战中容易翻车的四个场景及对应解决方案

工具是好工具，但用起来难免遇到问题。这一节我不写那种大而全的“FAQ”，只挑自己真实碰到的、也看到身边同事反复踩的四个场景来聊。

6.1 技能加载不到，AI 完全不知道 superpowers 是什么

如果是 Codex CLI，先排查全局和项目目录是否真的克隆对了位置。很多人在终端里一路复制粘贴，结果命令执行失败都没注意，目录压根没创建成功。如果目录没问题，再看AGENTS.md是否写对，路径是否跟实际一致。

如果是 Trae，优先重启。被缓存坑过太多次了，我现在养成一个习惯：每次往技能目录里丢新文件夹，都会顺手重启一次 Trae，不折腾。

6.2 技能文件太多，上下文被占爆

superpowers 的技能包如果内容很丰富，每个技能都有大量说明和示例，加载太多技能会吃掉大量上下文窗口，导致真正写代码时模型反而“变笨”。

我现在一般只保留 4 到 6 个高频技能在技能目录里，其他不常用的放备份目录。Codex 支持按需引用路径，未必需要把所有技能都堆在默认目录里。合理做法是：把技能库完整克隆到一个统一存放位置，然后只在技能目录里做软链接，或者通过AGENTS.md按项目需要引用指定技能。这就像工具箱一样，不会把家里所有工具都背身上，出门带个常用套装就行。

6.3 技能里的命令带风险，AI 直接执行了

superpowers 的技能工作流里经常涉及运行命令，比如执行测试、跑构建、Git 操作。这些命令在沙箱环境里没问题，但落到本地真实环境就有一定风险。有一次 AI 在执行技能步骤时，试图覆盖我本地数据库的测试数据，还好我提前设了确认机制，才没有出事。

解决方案分两层：第一层是在AGENTS.md里写明“执行任何可能产生破坏性影响的命令前，先向用户确认”；第二层是认真阅读技能包里SKILL.md的命令部分，自己心里有数，它到底会执行哪些操作。技能库是开源的，内容可以审，这份透明性也是我选择它的原因之一。

6.4 团队成员各自为战，技能版本不一致

如果你的团队决定用 superpowers，我强烈建议直接把技能目录纳入项目仓库，并去掉嵌套的.git。这样所有人在同一个提交点位上工作，永远不会出现你用的是旧版技能、我用的新版技能这种问题。

另外，技能更新不要在每个人电脑上分别git pull，而是在项目里统一更新，走正常的代码提交流程。这样做的好处是，技能变更跟代码变更一起过 Code Review，出问题能追溯，不会“莫名其妙 AI 行为变了”。

7. 自己动手写一个简单技能：其实没有想象中复杂

用了一段时间之后，你会发现自己有些特殊的团队流程是通用技能包没覆盖到的。这时候就该自己写技能了。别怕，写一个技能没有写一个插件那么复杂，本质上就是写一份结构化文档。

7.1 技能目录结构的设计

先建一个目录，名字就是技能名，目录里放一个SKILL.md，必要的话再加辅助脚本和示例文件夹。以下是一个标准技能目录的最小结构：

my-custom-skill/ ├── SKILL.md ├── scripts/ │ └── generate_report.py └── examples/ └── 示例输出.md

scripts/不是必须的，但如果技能涉及重复性操作，把操作脚本化会明显提升准确性。模型不擅长心算，让它跑一个脚本远比让它推理靠谱。

7.2 编写 SKILL.md 的关键：步骤要像菜谱

SKILL.md的格式没有特别严格的规范，但经验法则是：描述要具体到“何时做、做什么、怎么做、做完怎么验证”。不要写“分析代码质量”这种空话，要写“读取目标文件→检查是否有测试→运行已有测试→按严重程度输出 1-10 的质量评分并列出依据”。

我自己踩过的坑是写得“太像人话”——我以为自己描述得很清楚，但模型理解出来还是偏抽象。后来我学会了一个技巧：每写一步都问自己，这一步的输出产物是什么？能验证吗？如果不能验证，说明这一步骤设计得太虚。调试完技能之后，可以让 AI 按技能走一遍你准备的真实样例，看看它的行为是不是符合预期，不行就迭代描述。

7.3 把自定义技能接入工作流

把写好的技能目录放到全局或项目技能目录，然后按照前面的方式让运行时扫描到它。接着在一个新会话里显式要求 AI 使用新技能，同时准备好一个中等复杂度的测试任务，观察它是否真的按照技能里的步骤在做。

如果 AI 无视技能、回复依然很随意，多半是SKILL.md前几行的触发条件写得不够明确。你要在技能描述里写清楚“当用户要求 X 时，强烈建议使用本技能，并按以下顺序执行”，它才会在合适的时机主动想起这个技能。

8. 关于 superpowers 现状的一点个人感受

刷到的搜索词里还有“superpowers github”，我相信很多人跟我一样，第一反应是去仓库里看它到底更新得勤不勤、社区活跃不活跃。从我这段时间的使用看，它的迭代节奏蛮快的，技能内容也在不断完善。但说实话，这个项目的价值不在于有多少个 star，而在于它把“AI 编程助手应该怎么工作”这件事重新定义了一下。

之前大家讨论 AI 编程，重点都在“模型多大、代码生成准不准”；superpowers 让我意识到，模型能力只是下限，流程设计决定上限。同样一个模型，有技能和没技能，产出质量的稳定性差很远。模型本身还是会幻觉、会偷懒，但一套好的工作流能把这些问题兜住。它就像给一个聪明但散漫的同事配了一套标准作业程序，虽然不能保证他百分百不犯错，但至少不会毫无章法地乱来。

如果你手里已经攒了 Codex CLI 或者 Trae，真心建议今天花个二十分钟照着上面的步骤把 superpowers 装起来，不用多，先挑一个你日常最痛的工作流试一周。我自己用的第一周，最明显的变化不是代码写得快了多少，而是“返工率”降下来了——AI 交出来的活更贴近可用的状态，我不需要再像以前那样逐行盯着改了。这种体感差异，比任何 benchmark 数字都更能说服人。