企业官网建设流程全解析

最近在折腾给 Codex CLI 加技能包的事，发现一个叫superpowers的开源项目在开发者圈子里传得很快。它解决的是一个很具体的问题：AI 编程助手越来越强，但经常“有劲没处使”——你让它改个 bug，它不先定位根因就上手；你让它加个功能，它不写测试就开搞。superpowers 就是给这类终端 AI 助手装上的一套“工作方法”技能包，核心思路是让 AI 在动手前先学会规划、在实现前先写测试、在修 bug 前先复现。

这篇文章写给三类人：一是刚开始用 Codex CLI、觉得生成质量不稳定的朋友；二是已经在用 WorkBuddy、Trae 这类支持 skill 机制的开发工具、想统一管理 AI 工作流的人；三是单纯好奇“技能包到底怎么改变 AI 行为”的爱好者。我会把 superpowers 的构成、skill 的加载原理、在不同工具里的安装方式，以及实测下来哪些技能最实用、哪些坑别踩，一次讲完。

1. superpowers 的本质：先给 AI 立规矩，再让它干活

1.1 为什么叫“超能力”

先明确一个概念：superpowers 不是一个新的 AI 模型，也不是 Codex CLI 的插件，它是一套结构化的技能文件集合，来自开源社区，作者是 Perl 圈的老熟人 Jesse Vincent。这个项目最早是给 Claude Code 用的，后来因为 Codex CLI 等终端助手开始支持同类 skill 机制，就顺势扩展成了多工具通用的技能包。

它的命名很直白——把这些技能装进 AI 助手之后，助手就像获得了“超能力”。但这些能力不是让模型变聪明，而是约束模型的行为方式。普通情况下你让 AI“帮我修这个 bug”，它会直接开干；装上技能包之后，它会先按技能文件里的流程走：复现问题、读日志、缩小范围、提出假设、验证假设、改代码、写回归测试。整个过程像有个资深工程师在旁边盯着它按套路出牌。

这个思路和“提示词工程”最大的区别在于：提示词是临时的、碎片化的，而技能是持久化、可复用、带触发条件的。你不需要每次对话都重复“请先写测试再写实现”，技能文件会自动在合适的时机插入对应的工作流指令。

1.2 技能文件的结构

superpowers 仓库里每个技能都是一个独立目录，核心文件是SKILL.md，里面用 Markdown 写了技能的元信息和具体执行步骤。典型结构长这样：

skills/ ├── brainstorming/ │ ├── SKILL.md │ └── references/ │ └── ideation-techniques.md ├── test-driven-development/ │ ├── SKILL.md │ └── references/ │ └── tdd-workflow.md ├── systematic-debugging/ │ ├── SKILL.md │ └── references/ │ └── debugging-checklist.md └── writing-plans/ ├── SKILL.md └── references/ └── plan-template.md

SKILL.md的开头通常有一段 YAML 格式的元数据，描述这个技能的名称、适合什么场景、大概的触发关键词，后面就是正文指令。AI 在对话过程中读到这些元数据，判断当前任务是否匹配某个技能，匹配就自动加载对应的完整指令。

这个设计的好处是：技能可以独立演进。你觉得某个技能写得不好，直接改对应的 Markdown 文件；社区有人分享了更好的技能，复制进目录就能用。不需要改代码、不需要重装插件、不需要动模型配置。

2. skill 机制在不同工具里的加载逻辑

既然要装技能，就得先搞明白目标工具到底怎么识别和加载技能。这一块很多教程一句话带过，但实际踩坑往往都出在这里。

2.1 Codex CLI 的 skills 目录

Codex CLI 是 OpenAI 出的终端编程助手，天然支持 skill 机制。它会在你的用户目录下维护一个~/.codex/配置文件夹，技能放在~/.codex/skills/目录里，每个技能一个子目录，和前面说的结构一致。

Codex CLI 加载技能的逻辑是：在对话开始时扫描技能目录，把每个SKILL.md的元数据和摘要读进上下文，然后在对话过程中根据用户请求动态匹配。这意味着技能的描述写得清不清楚，直接决定它会不会被触发。你可以把SKILL.md开头的描述当成“广告位”，写清楚“这个技能解决什么问题、适合什么任务”，AI 才知道什么时候该用。

2.2 WorkBuddy 的 skill 接入

WorkBuddy 是 Rails 社区很活跃的 AI 编程工具，走的是和 Codex CLI 类似的路子。它支持通过命令行工具安装外部 skill，内置了类似workbuddy skill add之类的管理命令。我在它的文档里看到，它会把技能装进项目内部的.workbuddy/skills/目录，这样同一个技能可以跟着项目走，团队协作时所有成员拿到同一套技能配置。

这种“项目级技能目录”和 Codex CLI 的“用户级技能目录”有个重要区别：用户级技能对所有项目生效，项目级技能只对当前仓库生效。实际使用中我建议通用技能放用户级，项目特有技能放项目级。比如 TDD、调试这类通用技能放用户级，而“这个项目必须用 pytest + mock 的特定写法”这种约束放项目级更合理。

2.3 Trae CN 的技能配置

Trae CN 是字节跳动的 AI IDE，也跟进了 skill 机制。它通常是在 IDE 的设置面板里配置自定义技能，或者在项目根目录放.trae/skills/目录。和 Codex CLI、WorkBuddy 不一样的是，Trae 作为完整 IDE，技能不仅影响对话补全，还会影响编辑器里的内联操作，加载时机更复杂。

我的经验是：在 Trae 里装技能，最好先确认版本支持 skills，然后在设置里打开“自定义技能”开关，把技能目录指过去。Trae CN 的文档更新比较勤，安装前建议先看一眼当前版本的官方说明，因为不同小版本之间技能加载逻辑可能有差异。

3. Codex CLI 安装 superpowers 的完整流程

这一节是全文最“抄作业”的部分。我用 Codex CLI 为例，从零开始完整走一遍。

3.1 准备环境

安装之前先确认两件事。第一，Codex CLI 版本不能太老，我建议至少是0.x的较新版本，因为旧版本对 skills 的支持不完整。第二，确认你的终端能正常跑 Codex CLI 的命令，即codex --version能输出版本号。

codex --version mkdir -p ~/.codex/skills

第二行命令先建好技能目录，后面会用到。

3.2 克隆仓库并链接技能

从 GitHub 克隆 superpowers 仓库到本地任意位置，然后把仓库里的skills目录里的技能软链到~/.codex/skills/。我习惯用软链而不是直接复制，这样之后git pull拉取最新版就能自动更新技能，不用重复复制。

cd ~/Projects git clone https://github.com/obra/superpowers.git cd superpowers # 把仓库里的 skills 目录下的所有技能软链到 Codex CLI 的技能目录 for skill_dir in skills/*/; do skill_name=$(basename "$skill_dir") ln -sfn "$(pwd)/$skill_dir" "$HOME/.codex/skills/$skill_name" done

执行完可以用ls -la ~/.codex/skills/确认软链是否创建成功。如果只想装其中某几个技能，就不要用循环，直接软链单个目录，比如：

ln -sfn ~/Projects/superpowers/skills/systematic-debugging ~/.codex/skills/systematic-debugging

3.3 配置 AGENTS.md 让 AI 感知技能

技能目录创建好了，还要让 Codex CLI 知道“你有这些技能可以用”。这一步是关键。在项目根目录或者用户目录下创建AGENTS.md文件，里面告诉 AI 技能的存放位置和使用原则。我通常写在用户级，也就是~/.codex/AGENTS.md，让所有项目都生效：

# Skills 本环境包含一组可用的技能包，位于 ~/.codex/skills/ 目录。 当任务匹配某个技能时，请先读取对应的 SKILL.md 并严格遵循其中的步骤。 常用技能包括： - test-driven-development：编写新功能时使用，先写测试再写实现。 - systematic-debugging：排查 bug 时使用，按系统化流程定位根因。 - writing-plans：复杂任务开始前使用，先产出实施计划。 - brainstorming：需求模糊时使用，先梳理方案再动手。

这里有个细节：AGENTS.md本身就是 AI 的“贴身指南”，Codex CLI 在每次会话启动时都会读到它。所以你不需要在每次对话里提“你有技能”，它自己就知道。

3.4 验证安装是否生效

验证分两步。第一步，进入 Codex CLI 交互界面，输入一个和某个技能强相关的指令，比如“我需要重构这个模块，但我对方案不确定”，看它是否会自动触发brainstorming技能，输出方案而不是直接改代码。第二步，直接输入“你有哪些技能可用”，看它能否列出~/.codex/skills/里的技能清单。

如果它完全没反应，大概率是技能描述写得太含糊，AI 判断当前任务不匹配；或者AGENTS.md路径不对。我建议在AGENTS.md里把技能描述写得直白一点，AI 是读字面意思的，别让它猜。

4. WorkBuddy 与 Trae CN 安装的差异点

Codex CLI 的流程走通之后，WorkBuddy 和 Trae CN 就相对简单了，因为它们的设计逻辑相似，只是命令和目录位置不同。

4.1 WorkBuddy 安装步骤

WorkBuddy 官方提供了安装外部 skill 的命令。根据社区里流传最多的用法，装 superpowers 的方式是：

workbuddy skill add superpowers

这条命令会从 GitHub 拉取 superpowers 仓库并安装到当前项目或用户目录。如果你的网络环境拉取 GitHub 不稳定，也可以手动克隆后复制到.workbuddy/skills/目录，效果一样。

装完之后在WorkBuddy会话里测试一下 TDD 技能是否被触发。WorkBuddy 的日志输出比 Codex CLI 详细，如果技能没加载，日志里通常能看到原因，这点比 Codex CLI 友好。

4.2 Trae CN 安装步骤

Trae CN 走的是 IDE 设置路线。打开设置面板，找到“技能/Skills”相关选项，开启自定义技能，然后把superpowers/skills/目录添加进去。如果你用的是项目级配置，也可以把技能目录复制到项目根目录的.trae/skills/。

Trae 有个特殊点：它对SKILL.md的解析比较严格，YAML 元数据里的字段如果格式不对，整个技能会被忽略。所以从仓库直接复制的技能一般没问题，但你自己改过元数据的技能要特别留意格式，建议用在线 YAML 校验工具检查一遍再放进去。

此外，Trae CN 里不同的模型对技能的遵循程度有差别。本地小模型和云端的旗舰模型，在“是否严格执行技能步骤”这件事上表现差异很大，实测下来大模型执行得更稳定。如果你发现技能装了但 AI 不听话，先检查是不是模型选得太小。

5. 核心 skill 逐个拆解：规划、TDD、调试到底能干什么

装了技能包之后最关心的就是：里面到底有哪些技能、每个技能怎么影响 AI 的行为。我把最常用的几个拆开讲。

5.1 brainstorming 与 writing-plans：让 AI 先想清楚再做

这两个技能解决的是同一个病：AI 太着急。你给 Codex CLI 一个需求，它恨不得马上输出代码。brainstorming会在需求模糊时强制 AI 先提出多种方案、列出权衡、让你确认后再往下走；writing-plans则是把大任务拆成有依赖关系的步骤，并输出一份带验收条件的执行计划。

我实际用下来的体会是：这俩技能搭配使用效果最好。需求模糊时先brainstorming梳理方向，方向定了再writing-plans产出步骤。步骤拆得越细，后面执行越不会跑偏。这就像写代码之前先画架构图，看着多了一步，实际上省了返工的时间。

5.2 test-driven-development：先写测试再写实现

TDD 技能是 superpowers 里最有“性格”的一个。它要求 AI 在写任何功能代码之前，先写一个会失败的测试，然后运行测试确认失败，再写最小实现让测试通过，最后重构。这个流程听起来简单，但普通对话里 AI 几乎不会主动这么做。

装上之后，你只要说“用 TDD 实现这个函数”，它就自动进入“红灯-绿灯-重构”的循环。测试文件写在哪个目录、用什么测试框架、怎么运行单个测试，这些它都会从项目上下文里推断，不需要你额外交代。这个技能对测试基础设施比较完善的项目帮助最大；如果项目本身没有测试环境，技能会先引导你搭建基础测试框架，这本身也是好事。

5.3 systematic-debugging：按流程找根因，不瞎改代码

systematic-debugging是我个人最喜欢的技能。它的核心是让 AI 遵循一套排错流程：先复现问题，再收集信息，然后提出假设，用实验验证假设，找到根因后修改，最后写回归测试。整个过程会要求 AI 输出“当前假设”和“验证结果”，而不是闷头改一行代码就说修好了。

这个技能在真实项目里特别有用。普通的 AI 调试方式经常是“猜一个原因、改一下、跑一遍、不行再猜”，有时候碰巧改对了，但不知道为什么。系统化调试让 AI 把每一步推理都摆在明面上，你一眼就能看出它在往哪个方向排查，就算最后没解决，你也能基于它的排查过程给出下一步指引。

5.4 其他值得关注的技能

仓库里还有其他技能，比如code-review（让 AI 按审查清单检查代码）、commit-message-writing（根据 diff 生成符合规范的提交信息）、writing-prd（把需求整理成产品需求文档）等。这些技能触发频率不如前三个高，但特定场景下很省事。比如code-review对刚写完的大改动做一轮系统检查，能发现不少潜在的边界问题。

我自己习惯在合入代码前用这个技能让 AI 以“挑剔的审查者”身份过一遍改动，效果比让 AI 直接“帮我检查代码”好很多，因为它会按清单逐项检查，而不是泛泛地夸你代码写得不错。

6. 实测体验：哪些场景提升最明显，哪些坑要躲

6.1 提升最明显的三个场景

第一，新功能开发。以前让 Codex CLI 直接写一个新模块，经常写到一半发现方向不对，重来成本很高。开启writing-plans+test-driven-development之后，它会先给方案、再按测试驱动的方式推进，虽然生成的代码速度感觉慢了，但一次通过的几率高了很多。

第二，疑难 bug 排查。有一次遇到一个只在特定数据量下才出现的性能问题，我自己排查了半天没头绪，让 Codex CLI 用systematic-debugging技能分析，它按流程列了五个假设，逐个用采样数据验证，最后定位到一条在数据量大时走错索引的查询。这个过程它全程输出推理步骤，我很清楚地看到它是怎么排除其他假设的。

第三，代码审查。对于自己刚写完的大改动，让 AI 用code-review技能过一遍，能发现一些肉眼容易漏掉的边界情况和资源释放问题。它不像真人审查会有情面，清单上列了什么就查什么。

6.2 实际踩过的坑

坑一：技能描述被改坏导致触发失灵。我一开始觉得某个技能的描述写得不够“高级”，自己改了几句，结果反而导致 AI 识别不了触发条件，那个技能彻底沉默了。后来我意识到，技能描述不是给人类看的，是给 AI 做语义匹配用的，最好保持原样，最多补充例子，不要大幅删改。

坑二：多个技能同时触发导致指令冲突。有一次我让 AI“给这个接口加功能并保证不破坏现有逻辑”，结果test-driven-development和code-review同时被触发，AI 的行为变得很割裂，一会儿在写测试，一会儿在审查已有代码。解决办法是在指令里明确优先级，比如“先用 TDD 写，写完再 review”，把技能的执行顺序说清楚。

坑三：项目级技能被提交进仓库造成团队困惑。WorkBuddy 和 Trae 的项目级技能目录如果不加.gitignore，软链或复制的技能文件会被提交进仓库，其他成员 pull 下来之后可能会激活他们本不想启用的技能。我的建议是技能目录加入.gitignore，需要共享的技能单独放一个配置文件说明，让大家各自安装。

6.3 我的使用建议

如果你刚开始接触，我建议不要一次装全部技能，先装test-driven-development和systematic-debugging这两个，用一周感受变化，再逐步增加。装多了之后 AI 在技能选择上会犹豫，反而影响响应速度。

另外，superpowers 里技能的执行效果和底层模型能力有直接关系。能力强的模型能严格按技能步骤执行，能力弱的模型可能会“跳步”，比如 TDD 技能要求先跑测试确认失败，但模型直接跳到了写实现。如果你发现技能流程没有被完整执行，先换更强一点的模型试试，往往比调试技能配置更有效。

最后说一个更新习惯：superpowers 仓库本身迭代很快，我的做法是每周git pull一次，看更新日志里有没有修复我踩过的坑。技能包这种东西，社区维护者的实际经验比你自己摸索的要多得多，跟着更新不会吃亏。