企业官网建设流程全解析

1. superpowers 是什么：给 Codex CLI 装上“技能面板”

最近在开发者圈子里，“superpowers”这个词出现得越来越频繁。如果你平时用 Codex CLI 或者其他命令行编码代理，大概率能明显感受到一件事：这类工具做简单任务很利索，但一旦涉及具体项目的代码规范、目录习惯、框架版本差异，就得反复调教。模型不是不行，是缺少上下文，缺少对工程经验的封装。

superpowers 的出现，正好切在这个位置上。它是一套面向 CLI 编码代理的增强配置框架，核心是“技能（skills）”机制。你可以把技能理解成一个带输入输出规范的提示词单元，里面不仅写清楚了任务怎么做，还能附带脚本、模板、校验规则。比如项目里常见的“代码审查”“测试用例生成”“依赖升级”这类高频操作，原本每次要敲一大段说明，现在可以封装成一个技能，让整个团队复用。

这套东西火起来，和 Codex CLI 的走红是同步的。很多人都在搜“codex superpowers”，就是因为 Codex 本身提供了 Agent 式的命令行交互，但缺少成熟的工程化脚手架，superpowers 正好补上这一环。更有意思的是，不少主做 AI 工程化工具教程的自媒体（比如 worbuddy 这类讲“怎么用 superpowers”的内容）也开始把它当做一个独立章节来讲解，这说明它已经从个人脚本进化成一套可传播的方法论。

从我这个常年赖在命令行干活的人的角度看，superpowers 的核心价值不在于多了一个命令，而在于它让 AI 协作从“临时对话”变成了“可积累的资产”。代码写多了你会意识到，真正值钱的不是某一次生成结果有多好，而是你能否把一套有效的做事方式沉淀下来，让下一次、下一个人也能稳定复现。superpowers 的目录结构、技能注册、触发规则，本质上都在做这件事。

1.1 为什么常规的 AGENTS.md 不够用

很多项目已经在用 AGENTS.md 给 Codex 提供项目说明，这种方式是不是够用？说实话，在小项目里是够的，我也见过不少团队靠一份精心维护的 AGENTS.md 就能把模型调教得很好。但项目一复杂，AGENTS.md 越写越长，最后变成一本没人想读的说明书。模型每次都要把整份文件塞进上下文，既浪费 token，又抓不住重点。

superpowers 的思路恰恰是反过来：不再给模型一份大而全的说明，而是把任务拆成一个个可独立加载的技能包。模型碰到具体场景，只加载对应的技能。用的时候取，不用的时候不占上下文。这个思路，和平时整理代码库时的模块化思想一脉相承，但真正落实到 CLI 代理上，效果要远好于“一段提示词打天下”。

我见过不少团队把 AGENTS.md 当成万能池，什么规范都往里扔。结果项目一迭代，文件里既有过时的库名，又有前后矛盾的规则。模型在混乱上下文里挑挑拣拣，输出质量非常看运气。技能机制强制你按场景组织知识，一次一次加载，思路会清晰得多。

1.2 一次真实体感：从“没头没尾”到“有板有眼”

我第一次跑通技能时的体感，至今记得很清楚。当时在一个 Spring Boot 项目里，我用 Codex 让它做一次 service 层的代码审查。没装 superpowers 之前，我必须手动补一大段背景说明：项目用的 Java 17、Spring Boot 3、Controller-Service-Mapper 三层结构、异常处理走全局 advice……光是这段话就要写一百多字，而且每次都要重写。

把这段逻辑写成技能之后，在 Codex 里只需要说“review-java 一下 UserServiceImpl”，模型会自己按技能里的步骤走：先读文件，再对照分层规范，最后按固定格式输出问题清单。前后对比就像请了一位“只带了笔记本的新人”和“提前看过项目资料的临时工”的差别，后者明显更靠谱。

2. 安装前必须搞定的环境：版本、网络与目录权限

打开终端做的第一件事不是装包，而是检查环境。我见过太多人一上来就 npm install，然后被各种报错劝退，最后得出结论“这工具不行”。其实大部分问题都出在环境上，按这个顺序检查，能省非常多事。

2.1 Node 版本要够新

superpowers 的运行时依赖现代 JavaScript 特性。按目前社区项目的通用要求，Node 18 以下基本跑不起来，而且报错还很隐晦。如果你看到类似 “Unexpected token '?'” 或 “SyntaxError: Cannot use import statement outside a module” 的报错，大概率就是 Node 版本太老。

装好之后先执行：

node -v

如果你还在用 14、16，趁早升级到 Node 18 或更高。我自己的开发机是 Node 20 LTS，用到现在没遇到什么兼容问题。Windows 用户建议用 nvm-windows 管理版本，macOS 用户可以用 nvm 或直接 homebrew，大家按各自习惯来就好。

2.2 Codex CLI 要先能跑通

superpowers 不是独立解决所有问题的工具，它的定位是给 Codex 这类 CLI 代理增强能力。换句话说，前提是你本机的 Codex CLI 已经能正常使用。安装前，先确认一下：

codex --version

如果显示 command not found，先回去把 Codex CLI 装好再继续。另外，建议尽量用最新稳定版。superpowers 对 CLI 的输出解析依赖某些较新的参数格式，旧版本容易出现“技能执行了，但执行结果没有回灌给模型”的诡异问题，这种问题查起来非常玄学。

2.3 全局安装时的 npm 权限

npm 全局安装会遇到一个老生常谈的问题：EACCES 权限报错。这种问题通常不是 superpowers 的锅，而是 npm 的全局目录没有给普通用户写权限。网上有各种极端做法，比如直接 chmod -R 777 某个 node 目录，我不是很建议这么干，改系统目录权限的风险太高了。

相对干净的方案是让 npm 使用用户级目录。执行：

npm config set prefix '~/.npm-global'

然后把下面这行加到你的 shell 配置文件（~/.bashrc 或 ~/.zshrc，macOS 上是 zshrc，Linux 上一般是 bashrc）：

export PATH="$HOME/.npm-global/bin:$PATH"

重新加载配置后，再执行 npm install。实测下来，这个方案在 Linux 和 macOS 上都很稳。Windows 用户通常用 nvm-windows 管理 Node，全局目录默认就在用户空间，基本不会撞上权限问题。

注意：安装前用 npm config get prefix 看一眼当前路径。如果显示的是 /usr/local 这类系统级目录，优先改成用户级目录再继续。

2.4 初始化模板与本地网络问题

superpowers 安装后首次初始化，会从默认仓库拉取模板内容。这个过程在网络不稳的情况下偶尔会卡住。如果你发现 init 命令一直停在 fetch 阶段，不要傻等，直接 Ctrl+C 中断。

我的做法比较直接：本地预先准备一个最小模板目录，用 init 参数指定本地模板路径。好处很明显，完全不依赖网络，而且能保证第一次跑通是在完全可控的环境里。后续排查问题也会简单很多。

3. 从零安装到第一个技能跑通的全过程

前置环境都搞定之后，安装过程本身其实很快。这里写一个完整的操作路径，方便你对照着做。

3.1 全局安装命令

npm install -g superpowers

安装完成后，用一个命令验证是否成功：

superpowers --version

如果输出版本号，说明安装正常。这一步通常不到一分钟。如果这一步就报错，大概率是前面讲的 npm 权限或 PATH 配置问题，回到第 2 节再检查一遍。

3.2 初始化技能目录

superpowers init

执行完之后，它会在你的用户目录下创建一个名为 .superpowers 的配置目录，同时会在当前项目里生成一个 .superpowers 的隐藏文件夹。前者放全局技能包，后者放项目专属技能包。

这个设计非常贴合日常的项目管理习惯：全局技能是自己的“军火库”，项目技能是团队共同维护的“规矩”。我个人的习惯是尽量把通用能力放到全局技能里，把和业务强相关的规范放在项目技能里，这样换新项目时，全局技能可以直接带走，不用重新配置。

3.3 初始化后的目录结构

我截取了一个比较有代表性的目录树，方便你对照：

~/.superpowers/ ├── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── unit-test-gen/ │ ├── SKILL.md │ └── templates/ └── config.json ./.superpowers/ ├── skills/ │ ├── api-design/ │ │ └── SKILL.md │ └── changelog/ │ └── SKILL.md └── triggers.json

可以看到，技能都是以目录为单位组织的，每个技能目录里至少要有一个 SKILL.md 文件。如果技能依赖脚本或模板，也可以放在同一个目录下，方便整体迁移。

3.4 从最小的 hello-skill 建立体感

不用一上来就研究模板技能，直接手写一个最简技能，能最快建立感性认识。在项目里创建 .superpowers/skills/hello-skill/SKILL.md，内容如下：

--- name: hello-skill description: 用于验证 superpowers 技能是否正常加载的最小技能 triggers: - 打个招呼 - 输出 hello --- 请用一句话回应，并说明当前项目使用的语言和框架。

然后在 Codex 会话里输入“我是这个项目的新手，先打个招呼”。如果技能加载成功了，Codex 的回应会变得有结构，而不是一句孤零零的“你好”。第一次跑通技能的时候，那种感觉挺奇妙的——不再是一个空荡荡的对话开场，而是像你日常带新人时，先递给他的一页项目速览。

3.5 验证技能是否真的被加载

有些人跑完 hello-skill 后不确定技能到底有没有生效，因为模型的回应可能比较随机。这里有一个非常实用的验证技巧：在 SKILL.md 里加一个明显的 side effect。

比如，在 hello-skill 的正文末尾加上一句：

回答结束后，请额外输出当前目录下的文件数量。

如果 Codex 照做了，说明技能确实进入了上下文。如果没做，就需要检查技能名称是否匹配、触发词是否写对、目录路径是否正确。这个办法看起来土，但比 debug 一个不可见的加载过程高效得多。

4. 核心机制拆解：技能文件的写作语法与触发规则

要真正把 superpowers 用好，必须理解技能文件的写法。和很多人想的不一样，SKILL.md 不是普通的 Markdown 文档。前面的 front matter 承担元信息声明的作用，正文部分才是给模型的具体指令。两者缺一不可。

4.1 front matter 里的四个关键字段

description 字段是最容易被低估的。模型判断一段任务该不该用某个技能，主要看 description 与用户输入的语义匹配度。写“对 Java 代码进行面向可维护性的代码审查”就比写“代码审查”好得多，因为前者包含明确的场景语义，后者可能匹配到一堆无关技能。

triggers 字段稍微特殊，它负责的是“用户提到这个词时强制加载这个技能”的机制。但注意，触发匹配不是万能的，模型如果判断技能与当前任务无关，即使触发了也不一定会采用。所以触发词最好是动作加场景的组合，比如“java review”或“生成单元测试”，而不是单个“检查”这种泛词。

4.2 正文的指令设计原则

正文部分，我强烈建议按“背景 - 目标 - 步骤 - 产出物”四个层次组织。背景交代为什么做，目标明确做到什么程度，步骤给出固定执行路径，产出物规定最终交付格式。

这里举一个真实用过的技能示例：

--- name: review-java description: 对 Java 代码进行面向可维护性的代码审查 triggers: - java review - 代码评审 --- 背景：当前项目采用 Spring Boot 3，遵循 Controller-Service-Mapper 分层规范。 目标：找出代码中影响可读性、可测试性和潜在性能的问题。 步骤： 1. 阅读目标文件的全部内容，梳理核心逻辑 2. 对照项目分层规范，标记架构层面的越权调用 3. 检查主要方法是否缺少异常处理或边界判断 4. 输出问题清单 产出物：按“严重程度 - 位置 - 问题描述 - 修改建议”四栏表格输出。

这份技能看起来简单，但真正跑起来会发现，它比在会话里反复强调“注意分层规范”要稳定得多。因为技能里的上下文是固定的，不会随着对话推进被稀释。每次调用都是一套同样的高质量逻辑。

4.3 触发规则的范围与优先级

superpowers 的触发机制分两层：项目级配置和用户级配置。项目级 .superpowers/triggers.json 里定义的规则，优先级高于用户级同名词条。这个设计很合理——团队想覆盖个人习惯时，直接在项目配置里压制即可。

我踩过的坑是，把 triggers 写得太泛。比如之前写了一个“检查代码质量”的技能，triggers 里有“检查”两个字，结果所有涉及检查的请求都会命中这个技能，导致模型频繁误加载无关技能。后来改成“code review java”这种动作加场景的组合，命中准确率明显提升。

4.4 公共技能包的使用与二次修改

从默认仓库拉来的公共技能包，建议先通读一遍再投入使用。公共技能包的作者有自己的项目背景，写得再通用，也未必契合你的工程环境。我拿到一个新技能后的标准动作是：先复制到项目技能目录，再按项目规范删改，最后才激活。

这个过程不会花多少时间，但能避开很多“技能很厉害，生成的东西却不能用”的尴尬。网上不少教程会把技能包当成“装上就能用”的黑盒，我持保留态度。任何关于代码库的抽象，都需要在你自己的代码库里重新校准一次。

5. Java 项目实战：一次 Spring Boot 代码审查的全程复盘

搜索词里出现“superpowers java”一点都不意外。Java 项目体量大、规范多、模型上下文容易爆炸，正好是技能系统最能发挥价值的场景。前几个月我在一个 Spring Boot 项目里做了一次完整的技能化改造，把整个代码审查流程沉淀成了一个技能。整个过程的经验值得展开讲讲。

5.1 痛点：跨文件审查的上下文断裂

那个项目大概有 30 多个 Maven 模块，代码审查如果只看单个文件，经常漏掉跨模块的耦合问题。以前我手动写审查提示词，写少了模型不懂业务背景，写多了 token 烧得飞快。

一个 service 类大概 500 行，手工写提示词可能要花 10 分钟，生成的结果还不一定符合团队规范。后来我把“Spring Boot 项目代码审查”封装成技能，把 Maven 模块结构、分层规范、命名规范、异常处理原则全部写进 SKILL.md，让 Codex 每次审查前自动加载相关上下文。

这份技能经过三轮迭代，最后稳定在一个 200 行左右的 Markdown 文件里，团队同事直接复用，不再各自维护一套提示词。整个过程的效率提升，远不是一次两次省几分钟的问题，而是把“个人经验”变成了“团队资产”。

5.2 编写针对 Spring Boot 的专属技能

具体编写时，我用的是前面讲的分层结构。背景部分写清楚了 Maven 模块划分和核心业务域，目标部分限定为“面向可维护性与可测试性”，步骤部分要求模型先定位 Controller、Service、Mapper 三层之间的调用链，再按层次逐层检查。

产出物部分，我强制指定输出“问题清单 + 修改建议”的表格，并且要求修改建议里必须附带代码片段。这样产出的审查结果，可以直接丢给开发同学照着改，不需要再做二次转化。

实测下来的效果非常明显。原来临时写提示词审查一个 service 类，质量全看运气；用技能跑，至少每次产出的格式是固定的，问题罗列也有据可循。“代码审查”不再是悬浮的指令，而成了一套工程检查单。

5.3 与项目 AGENTS.md 的配合方式

我没有把 superpowers 技能和 AGENTS.md 当成二选一的对立方案，而是让两者分工合作。AGENTS.md 只写项目定位、模块结构和构建命令，像一本“快速速查手册”；技能文件则承载具体任务的执行路径，像一本“操作手册”。

模型先读 AGENTS.md 建立全局认识，再按技能加载局部流程。这样做的好处是上下文占用低，逻辑也顺。如果两者内容发生冲突，我的处理方式很简单：以当前项目的 .superpowers 为准。团队既然费心写了项目技能，就不希望再被旧版全局规则干扰。

5.4 Java 生态特有的注意点

Java 项目的技能里，一定要包含构建工具的信息。Maven 和 Gradle 的命令差异很大，技能里不写清楚，模型很容易给出“现象上成立、实际跑不通”的伪命令。

另外，Java 技能里建议附带项目中使用 Lombok 的情况说明。很多代码审查问题，比如“缺少 getter/setter”“直接访问私有字段”，在不了解 Lombok 的项目里是问题，在用了 Lombok 的项目里就是误报。这个细节不写进技能，审查结果基本没法直接用。越是这种“项目特有知识”，越值得沉淀成技能的一部分。

6. 常见安装与使用问题：我踩过的坑和完整排查链路

这部分应该是很多人最想看的。我从报错现象出发，给出根因和解决思路，再展开讲几个典型的排查链路。

6.1 command not found 的完整排查链路

遇到 command not found，第一步不是疯狂搜索，而是按顺序检查。先看包装没装上：

npm ls -g superpowers

如果输出里没有 superpowers，说明安装没成功。再看可执行文件的位置：

npm bin -g

或

npm prefix -g

拿到路径后，用 ls 看那个目录里是否有 superpowers 可执行文件。最后一步，把那个目录加入 PATH，然后重新打开终端。

这个链路可以解决我遇到的至少一半 CLI 工具“装不上”问题。而且整个排查过程非常快，不会超过五分钟。

6.2 npm 官方目录导致的权限困境

用过 npm 的人，多多少少都撞到过第一次全局安装权限错误。常见建议是改 npm 目录的归属权限，但直接改系统目录是很危险的操作。更稳的路子是让 npm 假装自己是用户级工具，也就是前面第 2 节提到的 prefix 配置。

Windows 用户一般用 nvm-windows 管理 Node，全局目录就在用户空间，很少撞权限问题。macOS 和 Linux 用户，我给的建议始终是 npm config set prefix '~/.npm-global'。这个方法我用了一年多，从没出过问题。

6.3 技能不触发的三种可能

技能文件写好了，但模型就是不按技能走，最常见的就三种原因：

第一种是路径问题。项目根目录下的 .superpowers 如果和你的启动目录不一致，模型根本看不到技能。这一点在 IDE 集成终端里特别容易翻车，因为集成终端的工作目录可能不在项目根目录。

第二种是触发词问题。前面说过，触发词写太宽反而不好用。我遇到过把“检查”作为触发词的情况，结果什么任务都往那个技能上靠。改成动作加场景的组合之后，命中率立刻正常。

第三种是加载开关问题。全局配置 config.json 里有一个 enabled 字段，默认是 true。但如果你手动编辑过配置，很容易在不经意间把它改成 false。我排查这个问题时翻了半天目录，最后发现是自己在改参数时手滑加了一行 enabled: false。那种感觉，真是又气又好笑。

6.4 模板源拉取超时

superpowers init 默认拉取模板源，如果你访问那个仓库速度不稳定，就会一直卡在 fetch 阶段。这个问题最稳妥的解法不是换各种网络加速，而是直接从本地造一个最小模板目录，然后：

superpowers init --template ./my-template

这个方法完全绕开网络依赖，而且能让你完全控制初始化内容。我在团队内部推广时，都是直接分享一个打包好的模板 zip，大家导入后各自初始化，整个流程非常稳定，不受外部环境影响。

7. 理性看待 superpowers：技能扩展的边界与我的使用心得

到了最后一部分，想聊点可能泼冷水的内容。superpowers 能带来很多便利，但它的边界必须说清楚，不然期望管理会出问题。

7.1 技能系统的边界在哪里

技能机制优化的是“可复现的执行路径”，但不会替你思考。项目里最难的架构决策、需求理解、技术选型，这些依然需要人来完成。技能只是把“你已经想清楚的流程”固化下来，再让 AI 稳定执行。如果你自己都没想清楚流程，写出来的技能也就是一团浆糊。

公共技能包的质量参差不齐。引用别人的技能前，至少要确认三件事：维护活跃度、技能文件的产出物格式、是否依赖特定 CLI 版本。否则表面上装了一个“自动生成单元测试”的技能，实际跑出来的东西连编译都过不了，反而消耗更多时间调试。

7.2 上下文预算与技能粒度

技能不是越厚越好。一份 5000 行的技能，和一段塞满废话的 AGENTS.md 没有本质区别。过度膨胀的技能会让模型在庞大上下文里抓不住重点，最终的效果反而不如一份精简的指令。

我的经验是，单个技能控制在 100 到 300 行之间。超过这个体量，就拆成多个下级技能，用 dependencies 字段按依赖链加载。这和写代码时“一个函数不要超过一屏”的道理是相通的。另外，一个技能尽量只解决一个场景问题。把“代码审查”“测试生成”“文档生成”塞进同一个技能，只会让模型在任务切换时晕头转向。

7.3 从小白到熟练，我建议的成长路径

如果你刚开始接触 superpowers，我的建议是先别急着下载一堆公共技能包。先用最小的 hello-skill 跑通链路，再把你最常做的一件事封装成技能，哪怕它非常简单。比如“生成 git commit message”“整理 changelog”这类低风险任务，都是非常好的起步场景。

从简单技能开始，你才能真正理解这个机制的脾气。等理解到位，再去扩展，就不会迷失在别人的技能库里。工具终究是工具，价值仍然取决于使用者对工程问题的判断力。现在这套技能机制已经成了我工作流里像 Git 别名一样自然的部分，但它不是银弹，只是让有章法的协作变得更稳定。如果你也想试试，建议从今天最常做的那件小事开始，把它变成你的第一个技能。