企业官网建设流程全解析

这阵子我把 Codex CLI 从一个“会在终端里帮你写代码的助手”升级成了“自带全套项目流程的结对同事”，关键一步就是给装上社区里很火的那个 superpowers 技能包项目。它不是一个新框架，也不是另一个 CLI，而是一套打包好的技能文件集合，作用相当于给 Codex 预装各种开发场景下的“肌肉记忆”：从初始化工程、按团队规范落地代码、跑测试，到定位 bug 时先查什么，都有现成的流程可循。

对开发者来说，最直接的收益是：你不再需要每次重复交代“我们项目是 Java 17 + Maven，Controller 不直接操作仓储层，Service 要加事务，单测放 src/test”，Codex 会在任务命中技能描述时，自动把这套约定翻出来照着做。这篇文章我不打算复读 README，而是把安装方式、目录规范、Skill 文件原理，以及我拿一个真实 Java 项目跑通全流程的完整链路拆开讲一遍。适合刚听说 superpowers、想马上上手的人，也适合已经在用、但一直没搞明白“为什么技能时灵时不灵”的人。

1. superpowers 到底是什么：一套技能包，不是另一个 CLI

1.1 从“智能聊天”到“自带流程”：技能系统解决的核心痛点

坦白说，Codex CLI 本身的写码能力已经很强了，我第一周用下来的最大感受是：它像极了一个聪明但没人带过的实习生。你问它什么它都能答，但如果没人告诉它“我们项目的 Controller 层不直接操作仓库，要经过 Service；测试要写在 src/test 下；异常要统一包装”，它每次都有可能给你生成风格完全不一致的代码。

这个问题不是模型能力不够，而是上下文工程没做到位。普通交互里，项目的隐性约定全都靠用户在每次对话中临时口述，一旦需求跨文件、跨服务，这些约定很快就会在长对话里被稀释，输出质量自然往下掉。

superpowers 这类技能包项目的核心思路，就是把“老工程师脑子里那套做事步骤”写成结构化的技能文件，放到 Codex 能读到的地方。当任务匹配到某个技能的描述时，模型会主动把该技能内容读进上下文，按照里面定义的流程执行。跟普通 prompt 最大的区别在于，技能是可沉淀、可复用、可分享的资产，而不是每次临场发挥的一段话。

1.2 一个类比：它像给 AI 配了一本“项目 SOP 手册”

我常用一个整理仓库的类比来解释这件事。假设你要请一个临时工帮你整理仓库，你当然可以每次都口头交代：“先看货架上哪些箱子过期，过期的搬到退货区，没过期的按日期排序。”但如果这个临时工手里有一本写好的《仓库整理 SOP》，每次开工前自己翻一遍，你的效率会高很多，出错率也会低很多。

技能系统就是这本 SOP 手册。它把高频动作固化成“先做什么、再做什么、遇到什么情况怎么处理”的流程。Codex 面对一个任务时，先匹配技能描述，命中后读取技能正文，再开始干活。这样一来，只要技能写得好，输出质量就基本稳定，不再依赖你每次提问时能不能把话说全。

1.3 适合谁用，以及不适用边界

从我的经验看，superpowers 最适合三类场景：一是团队技术栈相对固定的项目，比如后端就是 Spring Boot + MyBatis，你可以把分层规范和代码风格固化成技能；二是个人长期维护的项目，把自己的常用命令、测试习惯、部署流程写进技能，省得每次从零解释；三是需要 Codex 产出可交付代码的场景，技能里的检查清单能明显减少返工。

但它也不是万能药。如果是完全一次性的问答，比如“这段 SQL 为什么报错”，技能反而多余；如果项目有大量私有业务上下文，但没有沉淀成任何文档，那技能也救不了，因为技能只是个模板，不是业务知识库；还有一个比较隐蔽的问题：如果技能没人维护，随着项目演进，过时的技能反而会误导 Codex。所以我的原则是，技能数量宁少勿多，每一条指令都要对得上当前项目的真实情况。

2. 安装与初始化：把 superpowers 装进 Codex CLI 的正确姿势

2.1 安装前置条件：确认 CLI 版本与环境

动手之前，先把基础环境确认一遍。因为我见过不少朋友一上来就 clone 仓库，结果放错目录，折腾了半天还不知道问题出在哪。这里有几个前置检查项：

• Codex CLI 能正常运行，输入codex --version能看到版本号；
• 系统里有 git，并且能正常 clone 公开仓库；
• 按你实际要跑的场景准备好运行时，比如后面要跑 Java 实战，至少得有 JDK 和 Maven；
• 终端所在的用户目录有写入权限，因为默认技能目录会放到家目录下。

如果你是先装好了 Codex，但之前没接触过技能类项目，建议先随便跑一次正常对话，确认模型调用没问题，再引入技能，这样后续排查时能少一个变量。

2.2 获取技能包：clone 还是下载 zip

在 GitHub 上搜superpowers codex，能找到对应的技能包仓库。通常有两种拿法：直接git clone到本地，或者下载 zip 再解压。我个人更喜欢 clone，因为后续拉新版本只要git pull就行。命令大概是：

git clone <你找到的仓库地址> ~/superpowers-src

注意我现在故意不把路径直接指到最终的技能目录，而是先放到一个临时位置。因为你想装的可能不是整个包的根目录，而是里面按领域拆好的多个技能目录。不同版本的 superpowers 仓库结构会不一样，常见的是仓库里直接有skills/目录，里面放着java-backend/、frontend-react/、testing/这类子目录；也有些仓库把技能分散在顶层各目录里。

这一步没有标准答案，一定要以你拿到的仓库 README 为准。我踩过最蠢的坑，是把整个仓库文件夹直接当成一个技能塞进~/.codex/skills，结果 Codex 一直说找不到技能，后来才发现里面真正的技能实体是下一级目录。

2.3 目录放对才算装好：全局与项目两级目录

技能目录最关键的一点是位置。社区实践里普遍约定的结构是：

~/.codex/skills/ # 全局技能 java-backend/ SKILL.md frontend-react/ SKILL.md

以及项目内的局部技能：

你的项目/ .codex/ skills/ project-specific/ SKILL.md

全局技能适合放那种跨项目通用的能力，比如“Java 后端规范”“编写单元测试”“日志排查套路”；项目内的.codex/skills适合放团队私有约定，比如“订单模块的错误码规范”“这个仓库的发布流程”。两者可以共存，而且项目内技能会覆盖全局同名技能，这一点后面在常见问题里还会细说。

把目录放对之后，技能文件本身也要注意命名格式。技能目录名一般用全小写加连字符，比如java-backend，不要用空格、大写或者中文。SKILL.md 这个文件名也是约定俗成的，有些版本也支持PROMPT.md之类，但为了兼容性和可预期，我建议一律用 SKILL.md。

2.4 验证安装：怎么知道技能真的被读到了

装完想立刻确认有没有生效，我通常会按顺序做三件事。

先直接问 Codex：“你会哪些技能？”如果它能列出你刚放进目录里的技能名，说明技能目录扫描没问题。这一步在不同实现里表现不一样，有的版本会明确列出，有的只会说“我可以在需要时参考技能”，但至少能看出它有没有感知到技能的存在。

再看有没有自动触发。比如你在对话里描述一个“帮我给订单接口加分页和缓存”的需求，这正好命中java-backend技能描述里的触发词，那么在输出计划时，模型应该会引用技能里的步骤，而不是自己重新编一套流程。

如果前两步都不满意，就用显式引用的方式测试，在提示里直接写@java-backend或者“请先阅读技能 java-backend 再开始”。大多数支持技能的系统都会响应这种显式调用。这一步能确认技能文件本身没坏，只是触发机制可能需要调 description。

3. 核心机制拆解：Skill 文件是怎么被 Codex 调用的

3.1 一个技能就是一个文件夹：SKILL.md 与配套文件

很多人第一次看技能包会觉得奇怪：为什么不是一个.json或者.yaml配置文件，而是一个文件夹加一个 Markdown？实际上这正是技能系统最聪明的地方。SKILL.md 是给模型读的指令文件，而同一个技能目录下可以放模板、示例代码、检查清单等附属资源，让技能不只是“一段提示词”，而是一个完整的能力单元。

一个典型的技能目录长这样：

java-backend/ SKILL.md templates/ controller-template.java examples/ service-layer-example.java checklists/ code-review-checklist.md

SKILL.md 是整个技能的主入口，它有一个固定的 YAML 头，后面跟着正文指令。正文可以用 Markdown 引用同目录下的其他资源，比如“Controller 层写法参考 templates/controller-template.java”。这样设计的好处是，模型需要模板时可以直接把文件内容读出来，而不是靠记忆里不稳定的知识硬编。

3.2 frontmatter 里的 name 和 description 决定了“激活率”

我在实战里发现，影响技能到底灵不灵的最大因素，不是正文写得有多详细，而是文件头那几行 frontmatter 写得好不好。一个标准的 frontmatter 大概是这样的：

--- name: java-backend description: 当需要开发或修改 Java Spring Boot 后端接口时使用。包含分层规范、事务处理、统一异常、单元测试要求。若涉及订单模块，请额外参考项目内技能 order-rules。 ---

这段 description 最关键的是开头 200 个字符左右。为什么？因为匹配机制基本上就是把用户的请求和所有技能的 description 做相似度匹配，开头内容越能覆盖高频触发场景，命中率越高。反面典型是只写“用于 Java 开发”，这种描述太宽泛，几乎没有任何区分度，模型在多个技能之间不知道怎么选，结果就是你的技能被视而不见。

我写 description 的经验是：先写“什么时候用”，再写“用了之后要遵守什么”。比如上面那个例子，“当需要开发或修改 Java Spring Boot 后端接口时使用”是触发条件，“包含分层规范、事务处理、统一异常、单元测试要求”是能力摘要。如果还有跨技能的强制依赖，也可以像例子那样补一句，但这句要克制，别写太多，否则匹配时反而分散注意力。

3.3 技能分层与互相引用：别把所有内容塞进一个文件

刚开始接触技能系统的人，容易犯一个毛病：想把整个项目规范塞进一个 SKILL.md，结果文件比需求文档还长。这是走不通的，因为 Codex 读技能文件跟人看文档一样，越短越容易抓住重点，而且模型上下文窗口有限，长技能会占用大量推理空间，反而降低代码质量。

正确的做法是分层。用一个主技能做“流程编排”，再拆成几个子技能做“具体执行”。比如java-backend主技能里写流程：

执行本技能时，按以下顺序读取并应用子技能： 1. 先读取 sub/understand-project/SKILL.md，了解项目结构和依赖； 2. 编码阶段读取 sub/write-service/SKILL.md； 3. 提交前读取 sub/test-checklist/SKILL.md，按清单检查。

这样每个子技能文件都短小聚焦，模型只在需要的时候读给对应阶段用，既节省上下文，又容易维护。我在实际项目里就是把“理解项目”“写代码”“补测试”拆成三个子技能，即便某个子技能更新，也不会牵连主技能的流程。

3.4 上下文工程：为什么技能要短、聚焦、可裁剪

说穿了，技能系统的本质就是上下文工程。模型再强，也是在有限的上下文窗口里做推理的。你塞给它 500 行规则，它可能记住前 100 行，后面就慢慢跑偏了。所以技能正文里的每一行都应该是可执行的动作，比如“读取 pom.xml 确认 Spring Boot 版本”“先写测试用例再实现”“异常统一由 GlobalExceptionHandler 处理”。

“请尽量高质量”“注意代码规范”这种话就是纯废话，它没有提供任何可执行的信息，模型看了也不知道该具体做什么。一个可裁剪的技能应该是这样的：指令之间有明确顺序，每一条都能对应到一个文件、目录或者动作，这样模型读到后面就算上下文被压缩，也至少能保留住高优先级的检查项。

另一个小技巧是：当技能需要跟其他技能联动时，用相对路径引用子技能或资源文件，而不是写绝对路径。绝对路径换台机器就废了，相对引用才能让技能包保持可移植性。

4. 实战复盘：用 superpowers 带 Codex 跑一个 Java 需求

4.1 场景设定：一个真实的遗留 Java 项目改动

这里我拿一个自己跑过的场景复盘：一个 Spring Boot 项目，需要给订单查询接口加“分页 + 缓存”，并且要补齐单元测试。项目本身有历史包袱：Java 17 + Maven，Controller 层很薄，Service 里直接写查询逻辑，团队规范是 Service 方法上加事务注解，测试统一放src/test/java下。

这种需求看起来很常规，但没有技能的情况下，Codex 经常会在细节上翻车，比如不加事务、缓存注解用错位置、测试只覆盖正常路径。引入 superpowers 之后，我做的是在项目里配置了java-backend主技能，并把“订单模块错误码规范”等团队特有内容放进了项目级技能。

4.2 开场指令怎么写：让技能自动被召唤

技能能不能被自动触发，很大程度取决于你开场指令里的“触发词”能不能跟技能 description 中的场景对齐。我当时是这样写的：

在 order-service 模块里改造 GET /api/orders 接口：按团队规范加分页和本地缓存，并补单测。请先参考 java-backend 技能中的规范，按里面的流程执行。

这里有两个关键动作。第一，需求描述里出现了“Spring Boot 接口”“加分页和缓存”“补单测”，它们正好命中java-backend和testing类技能的典型场景；第二，我加了“请先参考 java-backend 技能中的规范”这句显式指引，相当于告诉模型去读技能，而不是全靠它自己悟。

如果只写“给接口加分页”，模型可能压根不知道要遵守分层规范，也可能自作主张把缓存直接写在 Controller 层。触发词不是魔法，本质上是在帮匹配机制缩小范围。

4.3 过程中 Codex 执行了哪些技能序列

我观察到的执行流程大概是这样的，正好对应技能文件里的层级结构。

先进入理解项目阶段，Codex 自己读了pom.xml，确认 Spring Boot 版本和依赖，又扫了一遍 controller 和 service 的目录结构，才输出实施计划。这一步对应的是子技能sub/understand-project/SKILL.md，它让模型在动代码前先建立项目背景认知，而不是上来就生成一坨代码。

进入编码阶段后，它按java-backend主技能里的规范，把分页参数封装成 PageRequest，在 Service 层通过 Spring Cache 注解做缓存，事务注解按团队习惯加在公开方法上。Controller 层保持很薄，只负责参数校验和返回包装。这个过程我让技能里写了一条硬性要求：不允许在 Controller 里直接调用 Repository，模型确实遵守了。

最后是测试阶段，它先列了一个测试用例清单，包括正常分页、缓存命中、缓存失效，以及参数非法场景，然后再写 JUnit 代码。这个“先列用例再写测试”的习惯，就是技能正文里强调的流程，效果非常明显，测试覆盖面比之前无技能时的随机发挥要稳定得多。

4.4 同需求无技能对比：差距在细节

为了验证是不是 superpowers 的功劳，我后来故意在另一个分支上，不带任何技能重新跑了一遍同样的需求。结果是：代码能跑，但细节问题不少。Controller 直接用了仓库层返回的实体，没有做 DTO 转换；缓存注解加在了私有方法上，Spring 代理根本不会生效；测试只写了正常路径，非法参数和缓存失效都没覆盖。

不是说 Codex 没能力写对，而是它没有“必须这么做”的强约束。技能的价值就在这里：它在模型自由发挥的边界上划了一条线，把团队规范、易错点、检查清单直接焊死在执行流程里。对个人开发者来说这可能只是省心；对团队来说，这意味着不同成员用 Codex 的产出风格能拉齐到同一水平线。

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

5.1 技能说找不到/没被触发怎么办

这个问题我遇到至少三次，最后整理出一个排查顺序。先看目录结构，确认技能是放在~/.codex/skills/<技能名>/SKILL.md，而不是放错成~/.codex/skills/SKILL.md这种扁平结构；再看技能目录名是否含空格或大写字符，命名不规范确实会导致扫描失败。

如果结构没问题，就看 description 的触发词跟你的提问是否对得上。最常见的情况是用户问得很宽泛，比如“帮我优化代码”，而技能描述明确写的是“当需要修改 Spring Boot 后端接口时使用”，匹配不上自然就不会触发。最优解是把提问写具体，或者干脆显式写@java-backend来强制调用。

5.2 技能内容太长被截断

当技能文件超长时，模型可能只读到前半部分，导致后面的检查项全部失效。我一般建议单个 SKILL.md 控制在 200 行以内，超过就拆子技能。如果你发现技能里的检查清单时灵时不灵，多半不是模型偷懒，而是清单位于文件后部，上下文被压缩掉了。

我自己的做法是：把最重要的硬性规范放在前面，检查清单这种可以后置。另外把描述里的“必须遵守的顺序”放在技能正文的开头，这样即使后面被截断，核心流程也不容易丢。

5.3 技能与项目指令 AGENTS.md 冲突

Codex 支持项目级指令文件 AGENTS.md，当它跟技能里的规则冲突时，你会发现模型一会儿按技能走，一会儿按 AGENTS.md 走，行为很不稳定。比如 AGENTS.md 规定接口返回直接用实体，而技能要求一律走 DTO，模型就会很拧巴。

解决方法是明确优先级。我通常在技能最前面写一行：“本技能若无特殊声明，应当服从项目级 AGENTS.md 中的强制要求。”这样等于给了模型一个冲突解决原则，避免它在两套规范之间摇摆。反过来，如果你希望技能规则优先，也要写清楚，总之不能留白。

5.4 多套技能混用时的优先级困惑

装了一堆技能之后，你会发现模型有时候会同时触发多个技能，然后行为变得混乱。比如既有java-backend技能要求写单测，又有fast-prototype技能要求快速出代码别写测试，两者一起被召唤，模型就会精神分裂。

我的建议是：一个需求主用一套技能，其他技能当作资源按需读取。在 description 里明确“本技能用于需要完整交付的场景，若用户明确要求快速原型，则忽略测试相关步骤”，可以把潜在冲突的责任推到提问信息上。另外，别在同一个项目里同时启用两个定位重叠的大技能，这是最省心的办法。

下面把我会遇到的几个问题整理成一个速查表，方便之后对照：

收个尾：我踩过几次坑之后的几点心得

用了这段时间 superpowers，最大的体会是：技能不是越多越好，而是越准越好。一个写得精准、聚焦场景、能稳定触发的 Java 后端技能，远比堆二十个宽泛的“开发规范”技能有用。你看社区里吐槽“技能没用”的人，绝大多数问题出在 description 写得像散文，或者目录里塞了几十个同名鸡肋技能。

还有一个小建议：别指望技能一次就能写好。它跟代码一样需要迭代。我第一次写的 java-backend 技能太啰嗦，模型老是抓不住重点；后来把正文砍掉一半，再把最关键的规范提到最前面，触发率和执行质量都明显提升了。技能系统是个好东西，但它终究是工程问题，不是装个包就一劳永逸的买卖。