企业官网建设流程全解析

之前给 Codex CLI 做能力扩展时，最常遇到的问题不是模型不够强，而是每次换项目、换技术栈，都要在提示词里反复交代背景和规范。后来接触到 superpowers 这类技能包项目后，我发现真正值得沉淀的并不是某一个现成技能，而是一套“把任务标准化、把经验变成文件”的方法。这篇文章就围绕 obra / superpowers 项目，整理一份从安装到自定义技能的完整实操指南，覆盖环境准备、核心概念、安装配置、排错清单和工程建议。适合正在折腾 Codex CLI 的开发者，也适合想建立个人 AI 工作流的同学。

1. 背景：为什么需要 superpowers 这类技能包

1.1 从 AI 编码助手说起

Codex CLI 是 OpenAI 推出的命令行编程助手，开发者可以直接在终端里通过对话让模型完成代码编写、文件修改、命令执行等任务。相比在网页端提问，CLI 的优势在于它天然贴近本地开发环境：能读取项目文件、能执行测试、能结合 Git 状态理解当前进度，体验上更像是“团队里多了一个能操作终端的协作者”。

但随之而来的问题也很明显：模型每次对话都是“无状态”的，它只看到当前上下文窗口里的内容。如果你希望它按照团队规范写代码、按照指定流程做重构、按照固定模板生成接口，就需要在每一次对话里重新解释规则。对于长期维护的项目来说，这种重复沟通成本非常高。

superpowers 这一类技能包项目，就是为了解决这个问题而出现的。

1.2 “obra / superpowers” 到底是什么

从项目命名来看，obra / superpowers 是一个社区维护的 AI 技能包集合。它做的事情可以通俗地理解为：把一套经过验证的工作流、提示词、操作步骤和约束条件打包成结构化文件，让 Codex CLI 在开始干活之前先加载这些文件，从而把“临时提需求”变成“按标准流程执行”。

很多开发者把它称为“插件”，但从技术实现上看，它更接近“技能包（skill pack）”。它通常由若干 Markdown 文件组成，每个文件描述一个具体能力：比如代码审查、测试生成、依赖升级、文档撰写、架构分析。Codex CLI 读取这些文件后，会按照文件里定义的步骤去执行任务。

这里要提醒一点：由于“superpowers”这个名字在 AI 编码社区里出现过多个版本，网上能搜到不同作者的实现。有些是专门为 Claude Code 设计的，有些是兼容多款编程助手的。本文讨论的是如何在 Codex CLI 环境下安装和配置这一类技能包，具体仓库以你搜索到的最新版本为准。

1.3 适用人群与使用场景

如果你属于下面这几类人，那这个概念值得你花时间了解：

• 长期使用 Codex CLI 或类似工具完成编码任务的开发者。
• 团队里希望统一 AI 编码规范、减少人工提示词维护成本的技术负责人。
• 对“提示词工程”感兴趣，想把自己的工作方法沉淀成可复用资产的效率爱好者。
• 正在评估 AI 编程助手落地方式的架构师。

典型场景包括：新成员加入项目时，让 AI 自动遵循团队的代码风格；每次发版前，自动执行一遍安全检查；把“如何新增一个 API 接口”这类重复性任务固化成标准流程，让模型按流程执行而不是自由发挥。

2. 环境准备与版本说明

2.1 基础运行环境

在动手之前，先确认你的本机环境满足以下条件：

• 操作系统：macOS、Linux、Windows（建议优先使用 macOS 或 Linux，Windows 下需要额外的终端兼容性检查，如 Git Bash 或 WSL）。
• 运行时：由于 Codex CLI 通常基于 Node.js 分发，建议提前安装 Node.js 18 或更高版本。如果你不确定自己是否安装了 Node.js，可以在终端里执行node -v查看。
• 命令行工具：Git，用于拉取技能包仓库；以及一个你习惯使用的终端模拟器。
• Codex CLI：需要先能正常在终端中运行codex命令。

版本方面有一个现实情况：这类工具迭代很快，不同版本对技能目录的约定可能有差异。本文示例以常见环境为例，重点演示配置思路。如果你遇到“配置了但没有生效”的情况，优先查阅你当前版本的官方文档，不要盲目照搬旧教程。

2.2 安装 Codex CLI

Codex CLI 的安装方式以官方 README 为准。这里给出一种常见的 npm 安装思路，具体包名请以最新文档为准：

# 方式一：常见 npm 包名安装 npm install -g codex # 方式二：部分版本使用 @openai 作用域 # npm install -g @openai/codex # 安装后验证 codex --version

如果你是用 Homebrew 安装的，也可以使用类似命令：

brew install codex

安装完成后，先跑一次简单的对话，确认 CLI 可以正常连接模型服务：

codex "请输出 hello world"

为什么要先做这一步？因为后续安装 superpowers 技能包之前，我们必须确保基础链路是通的。如果基础命令都无法运行，后面排查起来会混入很多无关因素。

2.3 准备项目目录

技能包的加载，通常是以“项目目录”为边界的。每个项目可以在自己的目录下维护一套技能配置，避免跨项目污染。我建议按下面的结构规划：

my-project/ ├── .codex/ │ └── skills/ # 技能目录 │ └── superpowers/ │ ├── SKILL.md │ └── references/ │ └── workflow.md ├── src/ ├── tests/ └── AGENTS.md # 项目指令文件，用于告知 Codex 技能目录位置

这里需要注意：.codex目录是存放 Codex 配置的地方，skills子目录用于存放技能包。AGENTS.md是目前很多 CLI 编程工具都会读取的项目指令文件，作用是告诉模型“在这个项目里该怎么工作”。

不同版本的 Codex CLI 对指令文件的命名可能不一样，常见的有AGENTS.md，也有一些项目使用.codex/instructions.md。建议以官方文档为准。

3. 核心概念拆解：superpowers skill 是如何工作的

3.1 技能包的本质是“结构化任务说明书”

很多人第一次看到技能包时，会以为里面是代码插件或二进制程序。其实不是。大部分技能包的核心就是一个或多个结构化的 Markdown 文件，它们的作用是给模型提供“如何完成某类任务”的详细说明。

你可以把技能包理解为一份写给 AI 看的 SOP（标准作业程序）。它包含的不只是“做什么”，更重要的是“按什么顺序做”“做到什么标准算完成”“遇到异常该怎么处理”。

比如，一个“Python 代码审查”技能包，它可能会规定：

• 审查开始前，先读取项目中的README.md和pyproject.toml。
• 检查代码时，优先关注数据流和错误处理，而不是代码格式。
• 每个问题必须标注文件路径和行号。
• 最后按“严重问题 / 建议优化 / 风格提醒”三个级别输出报告。

这些规则如果靠每次对话临时输入，既容易遗漏又不稳定。把它放进技能包文件后，模型每次被触发该技能时都会自动读取并遵守。

3.2 一个技能包常见的文件结构

不同作者维护的技能包结构会有差异，但通常遵循一个通用模式：

superpowers/ ├── SKILL.md # 技能主入口，定义名称、描述、执行步骤 ├── references/ # 参考资料目录，存放补充说明 │ ├── workflow.md # 详细工作流说明 │ ├── examples.md # 输入输出示例 │ └── troubleshooting.md # 常见问题处理策略 ├── scripts/ # 可选目录，存放辅助脚本 │ └── precheck.py └── assets/ # 可选目录，存放模板、图片等资源

其中SKILL.md是最核心的文件。模型通常会先读取这个文件，判断当前请求是否命中该技能，然后按照文件里的步骤执行。

一个典型的SKILL.md包含以下部分：

• name：技能名称，用于识别。
• description：技能描述，说明这个技能适合处理什么类型的任务。模型会根据描述判断是否启用。
• steps：具体的执行步骤，建议按顺序编号。
• constraints：约束条件，比如“禁止修改测试文件”“必须使用绝对路径”等。
• output_format：输出格式要求，比如“先给结论，再给分析”。

3.3 技能加载与执行流程

虽然不同工具在底层实现上有区别，但一次技能调用大致遵循下面的链路：

1. 用户向 Codex CLI 发起请求，比如“用 superpowers 完成一次依赖安全审查”。
2. 模型读取项目指令文件（如AGENTS.md），发现skills目录中有可用技能包。
3. 模型根据请求语义，在技能目录中寻找匹配的SKILL.md。
4. 如果匹配成功，模型会完整读取SKILL.md，并将其中的步骤、约束、输出要求作为本次任务的额外上下文。
5. 模型按照技能定义逐步执行，过程中可以调用终端命令、读取文件、修改文件。
6. 执行结束后，按技能要求的格式返回结果。

这个流程的价值在于：技能包相当于给模型加了一层“方法论约束”。没有技能包时，模型可能会自由发挥；有技能包时，模型的工作路径是确定的、可预期的。

4. 实战：为 Codex CLI 安装 superpowers 插件

4.1 获取项目代码

既然技能包以文件形式存在，第一步自然是把仓库拉取到本地。这里假设你要使用的项目地址是一个 GitHub 仓库，具体地址请以你搜索到的最新版本为准。

# 进入你的项目目录 cd my-project # 拉取技能包仓库（示例地址请替换为实际仓库） git clone https://github.com/obra/superpowers.git .codex/skills/superpowers

执行后，你的项目目录下会出现完整的技能包文件。先确认关键文件是否存在：

ls -la .codex/skills/superpowers/

正常情况下，你应该能看到SKILL.md以及若干子目录。

如果你的网络环境无法直接访问 GitHub，也可以选择手动下载压缩包，解压后移动到相同位置。这一步不涉及复杂逻辑，核心目标只有一个：把技能文件放到 Codex 能读取的目录下。

4.2 将技能目录接入 Codex CLI

下载好技能包只是第一步，还要让 Codex CLI 知道“这个项目里有技能包可用”。常见做法是在项目根目录创建或修改AGENTS.md文件。

下面是一个最小示例：

# AGENTS.md 本项目使用 Codex CLI 辅助开发。在开始任务前，请先检查 `.codex/skills/` 目录下的技能包。 - 如果用户请求与 superpowers 相关，请先阅读 `.codex/skills/superpowers/SKILL.md`。 - 严格按照技能文件中定义的步骤执行任务。 - 遇到技能文件中未覆盖的场景，请先向用户说明，而不是自行猜测。

如果你使用的 Codex 版本支持在config.toml中配置额外指令，也可以在~/.codex/config.toml中加入类似的引用，但更推荐把指令放在项目内，这样团队成员拉到代码后也能自动生效。

4.3 在会话中验证技能

配置完成后，启动 Codex CLI，试着触发一次技能调用：

codex "请使用 superpowers 技能检查当前项目的依赖安全性"

如果技能包加载成功，你会看到模型的回答风格明显不同：它不再直接给一个笼统结论，而是会先描述工作流，比如“我将按照依赖审查技能的流程，先读取依赖清单，再检查已知漏洞库，最后输出报告”，随后按步骤执行。

你也可以直接询问模型当前有哪些可用技能：

codex "请列出 .codex/skills 目录下所有可用技能，并说明每个技能的用途"

这是一个非常好的验证手段。如果模型能准确列出技能名称和用途，说明目录配置已经生效。

4.4 查看输出与后续调整

技能首次执行完成后，不要急着把它当成“配置完事”。你需要检查两件事：

第一，模型是否严格按照技能文件中的步骤执行。如果它跳过了某些关键步骤，可能是技能文件的描述不够明确，也可能是当前模型版本对长指令的理解能力有限。这时可以简化步骤数量，或者把复杂的步骤拆分成多个技能。

第二，技能的产出是否满足你的预期。比如技能要求“输出至少包含风险等级和修复建议”，但实际输出只有风险等级，那就说明SKILL.md中的输出格式部分需要写得更具体。

技能包不是一锤子买卖，它需要在使用中持续迭代。

5. 进阶：自定义一个自己的 skill

5.1 场景与需求

安装现成技能包只是开始。真正让 Codex CLI 变得顺手的关键，是把你团队里重复性强的任务固化成自己的技能。这里举一个实战例子：假设你经常需要新增一个 Python 命令行工具的子命令，每次都要经历“创建入口函数、注册参数、写测试、更新 README”这四个步骤。你就可以为这个任务写一个技能包。

5.2 编写 SKILL.md 文件

首先创建目录结构：

mkdir -p .codex/skills/python-subcommand/references

然后编写SKILL.md：

--- name: python-subcommand description: 为 Python CLI 工具新增一个子命令的标准流程，适用于 argparse / click 风格项目。 --- # 技能目标 在项目中新增一个可用的子命令，并保证测试和文档同步更新。 # 执行步骤 1. 读取项目根目录下的入口文件（通常为 cli.py 或 main.py），理解现有命令注册方式。 2. 根据用户提供的命令名称和参数说明，新增子命令函数。 3. 如果项目使用 argparse，遵循现有的 add_parser 模式；如果使用 click，遵循 @click.command 装饰器风格。 4. 为新增子命令编写至少两个测试用例，覆盖正常调用和参数校验失败场景。 5. 更新 README 中的命令列表，补充新命令的用途和示例。 # 约束条件 - 不要修改与本次任务无关的模块。 - 所有新增代码必须遵循项目已有的日志风格。 - 测试文件必须放在 tests 目录下，命名以 test_ 开头。 # 输出格式 完成后按以下格式输出： - 新增文件列表 - 修改文件列表 - 测试运行结果 - 使用示例

这段配置里最重要的是description字段。模型会通过它判断当前请求是否应该启用该技能，所以描述要具体，最好包含场景关键词。

5.3 引用技能并实测

在AGENTS.md中补充一行：

- 如果用户请求新增子命令，请先读取 `.codex/skills/python-subcommand/SKILL.md`。

然后重启 Codex CLI，执行：

codex "给这个 CLI 工具添加一个 status 子命令，用来显示当前配置状态"

观察模型行为。如果技能正常生效，你会看到它先读取入口文件，再按步骤操作，最后输出完整报告。如果它没有按照技能文件流程执行，可以尝试在请求中显式提到技能名：

codex "使用 python-subcommand 技能，给这个 CLI 工具添加一个 status 子命令"

显式指定技能名，能大幅提高触发准确率。

5.4 迭代思路

技能包写完之后，建议至少连续使用一周，记录以下问题：

• 哪些步骤是模型经常忽略的？
• 哪些步骤其实不需要写进技能里，模型自己就能做？
• 哪些环节的输出格式还需要优化？

根据这些反馈逐步调整技能文件。一个好的技能包，应该让模型“照着做就能达到 80 分”，而不是“提供了思路但还需要大量人工修正”。

6. 常见问题与排查思路

6.1 技能没被加载

这是最常遇到的问题。表现是：模型回复内容很泛，完全没有参考技能文件中的步骤。

排查思路：

1. 确认技能文件路径是否正确：项目根目录是否在.codex/skills/下。
2. 确认AGENTS.md中的引用语句是否明确，是否提到了具体的技能文件名。
3. 重启 Codex CLI 之后再试，因为有些配置读取发生在启动阶段。
4. 用“列出可用技能”的方式，看模型能不能发现技能包。

6.2 安装后提示找不到命令

如果你在技能包的scripts/目录里放了辅助脚本，但运行时提示找不到命令，通常是依赖没有安装或路径问题。

解决方案：

# 给脚本添加执行权限 chmod +x .codex/skills/superpowers/scripts/*.py # 或使用绝对路径调用 python3 .codex/skills/superpowers/scripts/precheck.py

在技能文件中，建议明确写出脚本的启动方式，不要只写文件名，避免模型默认使用./执行。

6.3 生成结果不符合预期

如果技能被加载了，但输出结果与预期有偏差，常见原因是技能文件里的规则不够具体。

例如，“最后按清单格式输出”就不如“最后输出一个 Markdown 表格，包含风险等级、问题描述、文件位置、修复建议”清晰。模型是靠字面含义理解规则的，写得越具体，执行越稳定。

6.4 版本升级后行为变化

Codex CLI 或技能包本身升级后，可能出现之前可用的技能突然失效。这通常是两类原因：指令文件格式变化，或者技能文件中引用的 API 接口、命令格式过期。

遇到这种情况，优先查看官方更新日志，同时检查技能文件里是否引用了外部工具链。建议把技能包固定在项目目录内，而不是放在全局目录，这样版本变更的影响范围可控。

下面是一个常见的排查对照表：

7. 最佳实践与工程建议

7.1 把高频任务沉淀为技能

使用技能包最大的收益不是“让模型多干活”，而是“让模型稳定地按你的方式干活”。建议每次发现模型在某类任务上表现不错时，把当时的对话、步骤、输出格式整理成一份技能文件保存下来。

这个习惯坚持两个月，你就会拥有一套个人工作流资产。换项目、换团队时，这套资产可以直接复用。

7.2 技能文件要保持“小而专”

一个常见的误区是把所有规则写进一个巨大的SKILL.md。这样做的后果是模型在处理具体任务时要阅读大量无关内容，反而降低执行准确性。

更好的做法是：一个技能文件只解决一类问题。比如“数据库迁移审查”和“API 生成”分开写，而不是放在同一个技能工程下。每个技能文件的步骤尽量控制在 3 到 8 步之间，多出来的细节放进references/目录，按需读取。

7.3 与项目规范绑定，而不是全局滥用

有些开发者喜欢把技能包装到全局目录，这样所有项目都能用。但实际项目中，不同项目的技术栈、编码规范、发布流程差异很大，全局技能包容易造成“上下文污染”。

更稳妥的方案是：把技能包放在项目根目录的.codex/skills/下，让技能与项目一起版本管理。团队成员拉取代码后，自动获得相同的 AI 操作规范。

7.4 注意安全与权限边界

技能包本质上是给模型提供可执行的指令，这就意味着它会影响模型对本地文件系统的操作。使用第三方技能包时，先通读一遍SKILL.md和scripts/目录，确认没有可疑操作，再接入项目。

另外，在技能文件中可以增加约束，比如“禁止删除未纳入版本控制的文件”“禁止直接执行 git push 到远程分支”“所有危险写操作前必须向用户确认”。这些限制能显著降低误操作风险。

对于涉及生产环境的任务，例如发布、迁移、批量修改，务必先在测试环境验证流程，并确保技能文件中有回滚策略说明。宁可多一步检查，也不要让模型在未确认的情况下执行高风险操作。

7.5 持续维护技能版本

技能包不是写一次就结束的静态文件。随着项目演进，技能中的步骤可能需要调整。建议把技能包纳入 Git 版本管理，并提交清晰的 commit message。当模型执行效果出现波动时，可以通过 git diff 定位是哪一次改动引起的。

8. 总结与实践建议

本文围绕 obra / superpowers 这个项目，梳理了技能包的核心概念、安装方式、运行原理和自定义方法。你可以把它看作一份“在 Codex CLI 里安装和使用 superpowers 插件”的操作地图，也可以把它当成一套“如何为 AI 编码助手沉淀技能”的方法论。

很多人在安装完 superpowers 后，觉得效果不够惊艳，根本原因往往不是技能包本身不行，而是没有结合自己的项目做定制。如果你已经装好了技能包，我的建议是先不要贪多。选一个最近两周重复出现三次以上的任务类型，把它固化成一条技能，让 Codex 按你的标准流程执行。技能包的价值不在数量，而在于每一次调用都能产出可预期、可验收的结果。

下一步，你可以研究如何把技能包分享给团队成员，以及如何在 CI/CD 流程中复用这些技能文件。把 AI 编码助手从一个“问答工具”变成“懂你规范的工作流引擎”，这才是 superpowers 这类项目最有价值的地方。