企业官网建设流程全解析

最近我把手头的 AI 编码工作流彻底重装了一遍，起因是同事甩给我一个词：superpowers。他说这不是形容词，而是一套能直接装进 Codex CLI、WorkBuddy、Trae Work 这些 AI 编程工具里的“技能包”。我花了一个周末研究、安装、实用了几天，说句实话，这套东西对日常编码效率的提升是实打实的。这篇文章就把 superpowers 的技术原理、安装步骤、常用技能和个人踩坑记录完整整理出来，给正在折腾 AI Agent 工作流的朋友一个参考。

如果你已经受够了“让它改个需求，结果把我的代码拆散重写”这种场面，也受够了 AI 助手每次都要从零开始理解你的项目规范，那你会理解我为什么愿意折腾这套东西。继续往下看之前，建议你先确认一个问题：你手头至少有一个 AI 编程工具在正常使用，并且你已经能接受让 Agent 直接读代码库、改文件。如果没有这个前提，superpowers 装起来也白搭。

1. superpowers 到底是什么，以及为什么 AI 编程工具突然需要它

1.1 从“能写代码”到“会干活”，差的不是模型而是流程

过去一年我用过不少 AI 编程助手，最直观的感受是：模型聪明了很多，但干起活来还是像个“只会写代码片段的新实习生”。你问它一个问题，它能给出看起来非常正确的答案；你让它改一个模块，它改完可能连编译都不检查。问题不是模型智商，而是缺少工程流程。

举个例子，你让 AI 实现一个函数，它直接给你甩出几十行代码。可要是你在一个真实项目里，你会期望它先搞清楚这个函数的调用方、依赖、异常处理、测试覆盖，最好还能自己跑一遍测试。这些流程如果每次都靠你在对话里一遍遍交代，效率会很低，而且稍微漏一点，Agent 就会自由发挥。

superpowers 解决的就是这件事：把“工程方法”变成一套可插拔的“技能包”，让 AI 在合适的时候自动调用对应的流程，而不是每次靠临场发挥。

1.2 我理解的 superpowers：一套可插拔的 AI 技能框架

我一开始看到“superpowers”这个名字，以为是某个大模型插件，后来才搞明白：它更像一个技能框架，核心是一系列结构化的技能定义文件。每个技能会告诉 AI：这个技能在什么场景下使用，应该遵循哪些步骤，最终要输出什么格式。AI 编码工具（比如 Codex CLI、WorkBuddy、Trae Work）在运行时会把这些技能描述加载到上下文里，触发到对应场景时，按技能中定义的流程执行。

这套框架里最重要的一个文件叫 SKILL.md。它通常长这样：

--- name: tdd description: 当需要实现新功能或修复 bug 时，先编写并运行测试，再实现代码。 --- # TDD 技能 1. 先根据需求写一个失败测试。 2. 运行测试，确认它因为目标功能缺失而失败。 3. 编写最小实现让测试通过。 4. 运行完整测试套件，确认没有回归。 5. 提交前再跑一次格式化与静态检查。

当 Agent 拿到一个“实现登录接口”的任务时，它看到 tdd 这个技能覆盖当前场景，就会按这个流程走：先写测试，再写实现。比起直接生成代码，看起来多花了点时间，但最终产物的稳定性能高出一大截。

为了更直观，我整理了一个对比：

1.3 谁适合用？什么场景收益最大

说实话，并不是所有用 AI 写代码的人都适合装 superpowers。我总结下来，下面三类人受益最大：

第一类是重度使用 CLI 编程代理的人。比如你已经在终端里用 Codex CLI 做多轮任务，让 Agent 自己改代码、跑命令、读报错。这种情况下，一套完整的技能包能明显减少你“帮它擦屁股”的次数。

第二类是希望 AI 稳定完成多步骤任务的团队。比如“实现新功能 + 写测试 + 跑回归 + 更新文档”这种链路，原生 Agent 很容易漏掉其中一步，靠技能包可以把它固化下来。

第三类是团队里想统一 AI 编码规范的人。与其在每个人的系统提示词里复制粘贴，不如做成技能文件，放进同一个目录，所有人都用同一套标准和流程。

如果你只是偶尔用 AI 聊天窗生成一段代码，没有让 Agent 直接操作项目文件的习惯，那 superpowers 对你来说大概率是过度配置。先把这个基础设施搭起来再考虑它也不迟。

2. 安装前必须搞懂的两个问题：它靠什么跑，装完影响什么

2.1 核心组成：技能定义、触发规则和全局上下文

很多人第一次看到 superpowers 的目录结构会有点懵：怎么全是 Markdown 文件？其实这些 Markdown 就是它最核心的“程序”。每个技能目录下通常都有一个 SKILL.md，里面包含 frontmatter 和正文。frontmatter 里的name和description字段特别重要，因为工具扫描技能时，主要靠 description 判断当前任务是否需要这个技能。你可以把 description 理解成技能的“简历”，写得好不好，直接决定了 Agent 能不能在正确时机把它认出来。

除了单个技能文件，superpowers 还常带一个全局上下文文件，类似 AGENTS.md。AGENTS.md 是很多 AI 编程工具约定俗成的规则文件，放在项目根目录后，Agent 每次启动都会读取它。superpowers 会把一些通用工程原则写进去，比如“在任何修改前先确认变更范围”“不要在测试失败时继续堆功能”等。这些规则和技能文件配合，才能让 Agent 的行为更贴近老工程师。

2.2 它和 Codex CLI / WorkBuddy / Trae Work 的协作方式

这个可能是大家最困惑的地方：同一个技能包，怎么能同时适配三个不同的工具？其实这些 AI 编程工具在技能加载机制上有一套相似的约定：读取某个固定目录下的技能文件，并把匹配到的内容拼进上下文。superpowers 的安装脚本做的事情非常简单，就是把这些技能文件拷贝到工具约定好的目录里。

以我本地的目录为例：

~/.codex/skills/ # Codex CLI 默认技能目录 ~/.workbuddy/skills/ # WorkBuddy 默认技能目录 ~/.trae/skills/ # Trae Work 默认技能目录

装完之后，你打开任意一个工具，让它完成一个“给用户列表加缓存”的任务，工具的调度逻辑会先读取技能列表，发现里面有类似refactoring、tdd、performance的技能，就会把对应的 SKILL.md 内容注入到当前会话的提示词里。Agent 拿到这些提示词，再结合代码库上下文，按技能定义的步骤干活。

用一个生活化的类比：技能文件不是驱动，插上就能改变 AI 的“硬件”，它更像一本 SOP 手册。工具负责把手册翻到正确的一页，AI 负责照着手册执行。明白这一点之后，你遇到问题就知道往哪个方向排查了。

2.3 安装前注意：版本、目录和依赖

虽然 superpowers 是开源项目，安装命令看起来也无脑复制粘贴，但我在实操中还是踩过几个坑，提前说清楚可以帮你少折腾。

第一，确认工具版本。不少技能文件用了较新的 Markdown 解析特性或者 frontmatter 格式，旧版本工具可能识别不全。我见过有人的 Codex CLI 因为版本太老，技能目录扫描不到，装了等于没装。稳妥的做法是先把工具升级到最新稳定版。

第二，确认技能目录的真实路径。不同操作系统、不同安装方式，目录可能不一样。比如 macOS 上默认是/Users/你的用户名/.codex/skills，Linux 则要留意是不是被安装脚本写到了/usr/local/share这种全局目录。装完以后最好手动ls看一眼，别急着进入下一步。

第三，注意模型上下文长度。技能文件会在每次会话时占用一定上下文 token。如果项目本身很大，再叠加一堆技能，模型很容易“忘事”。建议先装少量高频技能，跑通之后再慢慢加。这个我在后面专门讲。

3. 实操：把 superpowers 装进 Codex CLI、WorkBuddy 和 Trae Work CN

3.1 Codex CLI 安装 superpowers：官方脚本与手动两种方式

我日常主力工具是 Codex CLI，所以先讲它。第一种方式是官方脚本安装，你只需要在终端里执行项目 README 里的安装命令，通常是类似curl -fsSL https://example.com/superpowers/install.sh | bash这种形式。跑完之后，脚本会往~/.codex/skills/下写入多个技能目录。

安装脚本执行完，我建议不要急着用，先做三件事。第一，确认技能目录已经生成：

ls ~/.codex/skills

第二，确认技能总数和目录名，比如tdd、code-review、debugging之类的名字。第三，跑一个最小验证任务。我常用的验证问题是：“请列出你当前可用的技能，并说明在什么场景下会使用它们。”如果模型能清楚地列出来，说明技能加载成功。

第二种方式是手动安装。这种方式适合网络受限、或者你想自己维护技能集合的场景。手动安装的核心就是下载技能目录里的 SKILL.md 等文件，按相同结构放进 Codex 的 skills 目录，然后重启 Codex CLI。手动安装没有魔法，只要目录结构正确，技能就能被识别。

3.2 WorkBuddy 安装 skill superpowers：图形界面与管理命令

WorkBuddy 是我最近在评测的另一个 Agent 工具，它和人交互的方式更偏向对话式，支持通过命令或市场安装技能。官方支持的命令大概是workbuddy skills install superpowers，如果你更习惯图形界面，也可以在 WorkBuddy 的设置面板里找到类似“Skills”的入口，搜索 superpowers 后一键安装。

装完之后，需要确认它是否有独立的技能目录。我这边实测，WorkBuddy 给每个技能生成的目录里除了 SKILL.md，还会有一个meta.json，记录版本号和依赖关系。这个不用太关心，只要记住一点：如果你想临时停用某个技能，直接把对应目录名改掉或移走即可，不需要卸载整个 superpowers。

需要提醒的是，WorkBuddy 安装 skill 后，有可能要新开会话才会生效。如果你发现当前会话里技能没有加载，先别急着重新安装，重启或者/new一个新会话再试。这是 Agent 上下文机制导致的正常现象，不是安装失败。

3.3 Trae Work CN 安装 superpowers skill：在 AI IDE 中开启外挂技能

Trae Work 作为集成度比较高的 AI IDE，装技能的方式比命令行工具更“图形化”一点。我用的版本里，侧边栏有一个“技能”面板，点开后可以搜索 superpowers，直接安装。如果你想手动安装，思路和前面一样：把技能文件放到 Trae Work 的工作区.trae/skills/目录下，再重启应用。

这里有个细节我一开始忽略了：Trae Work 的技能目录既有用户级，也有项目级。用户级技能对所有项目生效，项目级技能只对当前项目生效。如果你只是想在某一个项目里实验，直接把 superpowers 装进项目级的 skills 目录就够了，别全局装，免得影响其他项目。

另外，Trae Work 里技能的触发受当前打开项目的影响。如果你在项目 A 里安装了 superpowers，切到项目 B 前，最好确认项目 B 的 skills 目录下有对应文件，否则技能不生效。这个问题很隐蔽，我一开始排查了很久。

3.4 安装后必做的四件事

不管你是哪个工具，装完 superpowers 后建议按这个清单走一遍，能避免后面 80% 的诡异问题：

1. 挨个工具检查技能目录是否存在且能读取。
2. 用“列出当前可用技能”验证加载。
3. 先跑一个最简单的任务，比如“检查当前目录下最大的文件并解释原因”，确认技能没有影响基础能力。
4. 把你团队的工程规范补充到项目的 AGENTS.md 里，让 superpowers 的技能和团队规则互相配合。

这套检查逻辑不仅适用于 superpowers，你以后安装任何 skill 类插件都可以复用。

4. 上手用起来：几个让我“路转粉”的 superpowers 技能

4.1 任务拆解技能：从一句话需求到可执行的步骤清单

我第一个想夸的是任务拆解。以前我让 AI 干活，最怕它把一个复杂需求当成一个小改动来办。有一次让它“给项目加一个导出 CSV 的功能”，它直接打开主文件往里面塞了一段导出逻辑，没有考虑命令入口、文件命名、格式校验、错误提示这些事。装完 superpowers 之后，它接到复杂需求，会先输出一个任务清单，把目标拆成几个阶段，每个阶段标记了验收标准。

你可以直接这样提问：

请使用 superpowers 的任务规划技能，帮我完成“用户每次登录后，在后台记录一条登录日志，并提供一个查询接口”这个需求，先给出步骤，不要动手改代码。

这时 Agent 通常会先梳理现状，列出“数据表设计、日志写入时机、查询接口、测试用例、文档更新”等步骤，并且告诉你它打算先做哪一步。你确认后，它再开始动手。这个先规划再执行的习惯，对中大型需求价值极大，能让你在 AI“跑偏”之前及早拦住它。

4.2 TDD 技能：让 AI 先写红再写绿

TDD（测试驱动开发）技能是我认为最容易被低估的一个。很多人觉得让 AI 先写测试太麻烦，但实际上它会显著降低后面改代码的返工率。superpowers 中的 TDD 技能会强制 Agent 遵循“红-绿-重构”循环：先写测试并运行，看清楚失败原因，再写最简实现让测试通过，最后重构。

我印象最深的一次，是让 AI 实现一个带时区转换的日期解析函数。没有 TDD 技能时，它直接写了一个看起来正确的实现；有了 TDD 技能后，它先写了几个边界测试用例，包括夏令时、闰年、无效输入。测试果然先挂了一批，然后它才一点点补实现。整个过程我只需要在关键节点审查它的测试用例是否合理。对使用者来说，TDD 技能给你带来的不是“更快的代码”，而是“更敢让 AI 自动改代码”的信心。

4.3 调试与根因分析技能：停止“瞎改代码”

调试技能是我认为最能体现 superpowers 价值的地方。原生的 AI 遇到报错，经常直接猜测原因、修改代码，然后让你重新跑一次试试。如果没通过，它换个地方再猜一次。你要是录了一段操作过程，会发现它的大部分尝试都是在“打地鼠”。

装了调试技能后，Agent 的行为会变得很不一样。它先要求你提供报错日志和最小复现步骤，然后静下心分析调用链，定位可疑代码，再做一个最小改动。我记得有一次遇到一个偶发的内存占用问题，Agent 没有急着改代码，而是先让我在关键位置打印了几条日志，复现一次后，它根据日志推断是某个全局缓存没有被清理，而不是之前代码里看起来最可疑的死循环。这种“先取证、后动手”的思路，是很多原生模型不具备的。

4.4 自建自己的技能：把团队的 code review 规范做成 SKILL.md

superpowers 另一个让我喜欢的地方是，它不只是别人给什么你就用什么，你完全可以自建技能。我后来就把团队的代码评审清单做成了一门技能。具体操作很简单：在 skills 目录下新建一个子目录，比如code-review-team，里面放一个 SKILL.md，frontmatter 写好名称和描述，正文写清楚评审步骤和红线规则，示例：

--- name: code-review-team description: 对代码变更进行团队规范的代码评审，检查安全性、性能和可维护性。 --- # 团队代码评审 1. 先阅读 diff，理解变更意图。 2. 检查是否包含硬编码密钥或敏感信息。 3. 检查是否缺少必要测试。 4. 检查是否影响既有接口兼容性。 5. 输出评审结论，按 P0、P1、P2 分级列出问题。

保存后重启工具，再发起一次评审请求，Agent 就会按这套团队规范来输出评审意见。这个能力的意义在于，superpowers 最终不只是一堆别人写好的技能，而是一个让团队工程经验可复用、可版本化的框架。

5. 常见问题与排查技巧实录

5.1 装了没反应？先查这三处

很多朋友装完之后，发现 AI 表现和以前一模一样，第一反应是“是不是没装成功？”根据我的经验，大概率是下面三处之一出了问题。

首先是技能目录没有被正确扫描。你需要确认工具读的是你放技能的目录。比如 Codex CLI 可能同时存在全局配置和项目级配置，superpowers 装到了全局目录，但你的项目级配置文件里可能设置了一个空的其他目录，导致技能没加载。

其次是技能描述触发条件太苛刻。Agent 判断是否使用技能，主要看技能 description 和当前任务的相关性。如果你安装了很多技能，但任务的表述方式和 description 对不上，就不会触发。解决办法是说得直白一些，主动点名“请使用 xxx 技能”。

最后是工具没重启。技能加载通常发生在会话初始化阶段，旧会话里不会动态更新。装完技能后，新开一个会话再测。

5.2 提示“没有权限读取 skills 目录”

这个问题多出现在手动安装或脚本安装到系统目录的场景。原因是技能文件的权限设置成了只有 root 可读，或者你的用户对某个父目录没有读取权限。

我用一句话排查：

ls -l ~/.codex/skills

如果发现文件属主是root，就执行：

sudo chown -R $USER ~/.codex/skills

如果你把这些技能放在共享目录或通过符号链接引用的目录里，还要额外检查链接目标是否存在。符号链接断掉之后，工具会静默忽略整个目录，看起来就是“没装”。

5.3 安装脚本被安全策略拦截

有些公司的开发机装了终端安全代理，会对curl | bash这类执行方式产生告警或直接拦截。这里不鼓励你去关闭防护，更推荐的做法是手动安装：先下载脚本，逐行读一遍再执行，或者直接把技能文件手动拷贝到目录。

手动拷贝本质上没有风险，也不会触发安全告警。如果你确实需要使用安装脚本，建议用curl -fsSL <地址> -o install.sh先保存到本地，检查内容没有问题之后再bash install.sh，这样也比直接管道执行要稳妥。

5.4 模型上下文窗口被技能塞满

技能文件也不是越多越好。如果 superpowers 自带了几十个技能，而你全部装上，每次会话都会把它们的描述塞进上下文，token 开销不小，项目代码一多就会提示上下文超限。

我的做法是只保留高频技能，低频技能用单独目录存起来，需要时临时启用。另外一个技巧是，在技能描述上做减法，把 description 写得足够精准，这样 Agent 只会在相关场景加载正文，不会每个技能都完整读一遍。

5.5 快速排查表

6. 一些使用建议和我的个人体会

6.1 先小范围试点，不要一上来装全量技能

我在第一次使用 superpowers 时犯过的最大错误，就是一上来把所有技能都装上了，结果不仅上下文压力大，Agent 的很多行为也让我摸不着头脑。后来我把技能裁剪到五个左右，包括任务拆解、TDD、调试、代码评审和重构，整个体验立刻清爽了很多。建议你也这样：先选一个你最痛的点，比如“AI 不写测试”，只装对应的技能，用几周，再逐步增加。

6.2 把 superpowers 当成团队工程规范，而不是个人玩具

如果你是一个团队的 lead，我特别推荐把 superpowers 跟团队规范结合起来。你可以先把团队的代码规范、评审标准、发布检查清单写进技能，再让每个成员的 AI 工具统一加载。这样一来，大家用 AI 写代码，遵循的不再是每个人自己的“野路子”，而是团队沉淀下来的流程。这个过程本身，比装一个工具更加值钱。

6.3 后续还能怎么玩：自己写技能，沉淀自己的“超能力”

最后再分享一个我的扩展玩法。我把自己平时处理线上问题时的排查思路，写成了一门叫oncall-playbook的技能，里面包含了“先看监控、再看日志、最后看代码”的步骤，以及一些常用命令模板。之后每次让 AI 帮忙处理线上告警，它都会自动按照这个 playbook 走一遍，少漏掉不少关键环节。superpowers 的意义，不在于装完那一刻有多炫，而在于它给你搭好了一个沉淀经验的框架。用久了你会发现，真正强的东西其实是你自己总结出来的那套流程。

我现在的体会是：superpowers 不会让 AI 从笨变聪明，但它能让 AI 从“聪明但不可靠”变成“聪明且按套路办事”。对任何一个想把 AI 编码助手真正用到生产环境的人来说，这一步的重要性怎么强调都不过分。如果你也在折腾这些工具，建议今天花十几分钟先装一遍，跑一个简单任务试试，也许你就能体会到我说的“路转粉”是怎么回事了。