企业官网建设流程全解析

直接说结论：如果你手头有 Claude Code、Codex 这类 AI 编程助手，却总觉得它们"写代码可以，但干活没章法"，那superpowers这个技能包大概率能治好你的不爽。它不是又一个提示词收藏夹，也不是 wrapper 套壳工具，而是一套真正能装进 AI 助手里的"职业技能库"——把资深开发者平时做规划、写测试、查 bug、做代码审查的套路，固化成一批按需加载的SKILL.md技能文件。装好之后，你的 AI 不再是一问一答的聊天窗口，更像一个自带工作流意识的新人程序员：先想清楚再动手，先写测试再补实现，出了错会自己定位而不是瞎改。这篇就把我从安装到实际跑通项目的完整经验写出来，包括命令、踩坑和几个很关键的认知，希望能帮你省掉几天的摸索时间。

1. Superpowers 到底是什么：不是插件，是给 AI 装职业习惯

1.1 一个类比理解它的工作方式

你可以把superpowers理解成给 AI 编程助手装了一整套"职业技能包"，就像刚毕业的程序员进公司后，除了会写代码，还得有人教他：接到需求先拆解、动手前先画方案、写完代码要自测、出 bug 先看日志而不是瞎猜。superpowers做的事情就是这个——它把这类"职业习惯"写成结构化的技能描述文件，让 AI 在合适的场景下自动加载对应的工作方法。

它本身的实现原理并不玄乎：就是一整套SKILL.md文件，每个文件用固定的 Markdown 格式描述一个技能的目标、触发条件、执行步骤和注意事项。superpowers插件安装后，会在你的项目目录下生成一批这样的技能文件，AI 助手（比如 Claude Code）在对话过程中会主动扫描这些技能，一旦判断当前任务与你定义的技能匹配，就会自动把技能内容读进上下文并按照里面的流程执行。

1.2 它跟普通 Prompt 模板的区别

很多朋友看到这里会说：这不就是把提示词塞进项目里吗？我直接在对话里粘贴一段"请你先写测试再实现功能"的指令不也一样？

区别很大。普通 Prompt 模板是"一次性"的，你每次开新会话都得手动粘贴，而且 AI 很容易跑偏——你今天说"先写测试"，它照做了，明天换个需求它又忘了这回事。superpowers这类技能包的核心价值在于持续性和结构化：技能文件就躺在项目的.claude/skills目录下，AI 每轮对话都能感知到它们的存在，并且按照技能文件里定义的触发条件自动决定要不要启用。这相当于把"优秀的工作方法"从你嘴里搬到了 AI 的长期记忆里，不依赖你每次重复叮嘱。

还有一个容易被忽略的点：superpowers的技能定义里包含明确的退出条件和验收标准。比如一个调试类技能，它不只是告诉 AI"你要排查 bug"，还会要求它先复现问题、再定位根因、最后写一个验证用例来证明修复有效，每一步都有可检查的输出物。这种"端到端的流程约束"，是普通 prompt 很难做到的。

1.3 适合谁来用

这东西最适合三类人：第一，天天泡在 Claude Code、Codex 等终端型 AI 编程工具里的开发者，想把自己的工作流固化下来；第二，团队管理者，想把组里的编码规范、测试要求、review 清单统一"下发"给所有人的 AI 助手，新成员入职，AI 自动就按团队套路干活；第三，搞 AI 工作流研究的人，superpowers的SKILL.md机制本身就是一个很好的参考实现，对理解 agent 如何动态扩展能力很有价值。

2. 安装与初始化：5 分钟跑通第一套技能

2.1 前置环境准备

安装superpowers前，先确认几样基础环境：

• 电脑上装好Node.js 18 以上版本，superpowers的安装脚本和它的命令行工具依赖 Node 环境。
• 装好Git，绝大部分安装流程都是从 GitHub 拉取技能库，没有 Git 寸步难行。
• 安装并登录Claude Code（如果你用的是 Codex，后面我也会讲迁移思路，但官方对 Claude Code 的支持是最完整的）。

检查命令很简单：

node -v git --version claude --version

三条命令都能打印出版本号，说明前置环境没问题。我在 macOS 和 Ubuntu 上都跑过，Windows 的话建议用 WSL2，避免路径和权限问题。

2.2 安装主插件与初始化技能库

superpowers的安装入口是 Claude Code 的插件市场。打开 Claude Code 终端，输入：

/plugin marketplace add obra/superpowers

接着再输入：

/plugin install superpowers@latest

插件安装完成后，superpowers会要求你初始化技能库。在对话中执行：

/superpowers

这时它会询问你要在哪个目录生成技能，选择当前项目即可。初始化完成后，你会看到项目目录下多了类似这样的结构：

项目根目录/ └── .claude/ └── skills/ ├── brainstorming/ │ └── SKILL.md ├── test-driven-development/ │ └── SKILL.md ├── systematic-debugging/ │ └── SKILL.md ├── code-review/ │ └── SKILL.md └── ...

看到.claude/skills目录下出现一堆技能子目录，就是安装成功了。每个子目录就是一个独立技能，里面至少包含一个SKILL.md描述文件，有些技能还会附带参考文档、示例文件等资源。

注意：如果你用的是旧版本 Claude Code，可能不支持/plugin系列命令。这种情况建议先升级 Claude Code 到最新版，别去 hack 旧版——插件机制迭代很快，旧版踩坑不值得。

2.3 从技能市场加装更多技能

superpowers主插件自带了一批核心技能，但它的生态不止于此。社区里有很多人把自己整理的技能发布成了独立的技能包，你可以通过同样的插件市场机制加装。

在 Claude Code 里查看当前已安装的插件：

/plugin

它会列出所有已安装插件的状态。如果你想加装社区技能，一般是找到对应技能库的 GitHub 地址，然后：

/plugin marketplace add 作者名/仓库名 /plugin install 仓库名@latest

每次加装新技能后，建议在项目里简单测试一下，确认技能能被正确加载（怎么确认，我放到第四节细说）。

我个人的建议是：别一上来就装几十个技能。技能文件越多，AI 每次扫描的开销越大，而且容易互相干扰。先装superpowers自带的几个核心技能跑两周，觉得哪块工作流不顺再针对性地加装，这才是正路。

3. 核心技能拆解：这几类技能到底怎么干活

3.1 brainstorming 与规划类技能：让 AI 先想清楚再动手

brainstorming技能是superpowers里最容易被低估的一个。很多人觉得"头脑风暴"是虚的，但实际上，AI 编程助手最大的问题之一就是想得太少就动手。你让它"写一个用户登录功能"，它可能上来就生成两百行代码，结果连需求里三分之一的关键约束都没覆盖。brainstorming技能要解决的正是这个。

它的工作流程大致是：先要求 AI 向你提出一系列澄清问题，把你模糊的描述拆成明确的约束条件；然后基于这些约束生成多个可行方案，逐一分析优缺点；最后在方案达成一致后才给出具体实现计划。

用的时候，你不需要手动"触发"它——只要你在一段对话中表示要开始一个新功能，而项目里没有对应的现成方案，AI 可能会自动调用这个技能。不过我更推荐在需求较大时主动点名：

使用 brainstorming 技能，我们先梳理一下这个用户中心模块的完整需求。

实测下来，这个技能对两类场景特别有用：一类是你自己也没想清楚需求的时候，AI 会通过提问帮你把需求补全；另一类是需求里隐藏的技术债很明显（比如涉及老系统改造、权限模型变更），技能的提问环节能帮你提前暴露风险。

3.2 系统化调试技能（含 Java 项目适配）

systematic-debugging是我个人用得最频繁的技能。咱们平时让 AI 帮忙查 bug，最常见的现象是什么？AI 看完报错信息，直接就开始"猜"——猜一个原因，改一段代码，告诉你"试试看"。运气好能蒙对，运气不好来回折腾半天。systematic-debugging技能的核心约束是：先复现，再定位，再修复，最后验证。

它的执行步骤通常包括：

1. 要求 AI 先确认你提供的错误信息是否完整，必要时主动让你补充日志、输入数据。
2. 指定 AI 先提出至少一个可验证的"故障假设"，并设计一个最小复现步骤。
3. 在改动任何业务代码前，先添加或运行现有测试来复现问题。
4. 修复后必须用一个回归测试来证明 bug 确实被修掉了，而不是"碰巧通过"。

这套流程看着像教科书，但真正让 AI 执行起来，效果天差地别。如果不用技能，AI 在第三步就跳过去了，直接改代码；用了技能，它会在项目里先建一个失败测试，然后才动手，最后跑测试给你看结果。

关于热词里提到的superpowers java，我专门在几个 Java 项目里试过这套调试技能，适配得不错。只要你的项目是标准 Maven/Gradle 结构，技能会自动识别pom.xml或build.gradle，调用mvn test/gradle test来执行验证。有一个细节要注意：如果你的 Java 项目里已经有 JUnit 5 依赖，调试技能会优先用 JUnit 5 写复现测试；如果项目里没有测试框架，它可能会跟你确认后再引入依赖。建议在 Java 项目里提前装好 JUnit 5 和断言库，这样技能跑得更顺。

3.3 代码审查与文档生成类技能

code-review技能适合在合并请求（PR/MR）前使用。它会让 AI 以审查者身份阅读你的 diff，按"正确性、安全性、性能、可读性、测试覆盖"几个维度逐条给出意见，并且每条意见都要标注严重级别。如果你在团队里承担 review 职责，这个技能能帮你省掉大量的机械检查时间。

不过我要提醒一句：AI 的 code review 结果不能直接当结论，它更像是一个"初筛"。AI 对业务上下文的理解有限，一些涉及历史包袱的写法（比如某个看似多余的兼容逻辑）很可能会被它误报。我的用法是让 AI 做第一轮，我只看它标为"严重"和"高"的问题，中低级别的基本都是噪音和风格建议。

documentation类技能则比较适合给代码补充文档、生成架构说明，或者反过来，根据文档生成测试用例。它最大的好处是输出格式统一——技能文件里约定了文档要包含哪些章节、用什么语气、代码示例要怎么给，所以生成的文档风格是固定的，不会这次科普腔、下次论文腔。

4. 实操示例：用一个完整任务验证技能是否真的在工作

4.1 场景设定与技能调用

光看原理不过瘾，我拿一个实际场景来演示。假设我要在已有的 Node.js 项目里新增一个"带过期时间的本地缓存"工具函数。

首先，我会在 Claude Code 里明确要求：

请先用 brainstorming 技能帮我把这个需求拆清楚。核心要求：支持设置过期时间、缓存淘汰策略要简单、不引入额外依赖。

这时，AI 会按brainstorming技能的流程行动。你注意观察它的输出，如果它开始逐条提问（比如"过期时间精度要求到毫秒还是秒？""缓存容量有没有上限？""并发读写场景多不多？"），说明技能已经成功加载。

等需求拆完，让它进入 TDD 流程：

接下来用 test-driven-development 技能来实现。先写测试再写实现。

技能模式下，AI 会先问你要 Node 内置的测试框架（node:test）还是第三方库（Vitest/Jest），确认后才会动工。项目里如果没有package.json的 test 脚本，它会先帮你配置好，然后创建测试文件，跑一遍展示失败，再编写实现代码，最后跑全量测试验证。

4.2 怎么确认技能真的被"按需加载"了

很多朋友装完技能后发现 AI 好像没啥变化，就开始怀疑装了个寂寞。其实技能是否生效，是能观察出来的。

第一个信号：AI 开始"多问"了。如果你新建一个对话，直接说"帮我写一个工具函数"，没有技能时它大概率直接给代码；有brainstorming技能时，合理的触发路径下它会先追问需求细节。这是判断技能是否生效的最直观方法。

第二个信号：工作目录里会出现技能相关文件。比如 TDD 技能生效时，AI 会主动创建test/目录或补充package.json的测试脚本；调试技能生效时，它会在写修复前先创建一个复现失败的测试文件。

第三个信号（更精确）：查看 AI 的响应元信息。Claude Code 在执行过程中会打印它读入了哪些文件、执行了哪些命令。如果你看到类似.claude/skills/test-driven-development/SKILL.md的路径出现在上下文里，那就是技能被真实加载了的铁证。我一般会开启 verbose 模式观察几轮，确认技能加载过程没问题后，再关掉 verbose 正常使用。

4.3 迁移到 Codex：SKILL.md 协议是通用的

热词里有codex superpowers，很多人关心 OpenAI Codex 能不能用。答案是：能用，但要看版本和方式。

superpowers的核心产物是SKILL.md文件，这套格式本质上是一种开放约定：在一个约定目录下放置特定结构的 Markdown 文件，AI 在约定场景下自动读取。Claude Code 的约定目录是.claude/skills/，而 OpenAI Codex 的 AGENTS.md 体系同样支持按目录加载上下文。你完全可以这样做：

1. 在项目根目录建一个skills/子目录；
2. 把superpowers生成的.claude/skills/里的技能文件复制进去（或者复制核心的几个）；
3. 在AGENTS.md里加一段说明，告诉 Codex 在遇到相关任务时去skills/目录下查找并阅读对应的SKILL.md文件。

这样做的效果不如 Claude Code 插件那样的自动按需加载（Codex 不会像 Claude Code 那样主动扫描并自动触发），技能文件更像一份"被索引的参考文档"，但总比每次手动粘贴提示词强得多。我实测下来，TDD 和 debugging 两类技能迁移到 Codex 后的可用度相当高，因为它们的指令大多不依赖具体模型能力。

4.4 WorBuddy 之类的 agent 工作台场景

如果你用的是 WorBuddy 这类把多个 agent 能力聚合起来的工作台，superpowers也是可以接的。思路和 Codex 一致：把技能库放到项目约定目录，然后在工作台的系统提示/项目说明里显式声明技能目录的路径和触发规则。这里我不再展开，毕竟这类工具迭代很快、配置路径经常变，直接看你手头版本的文档最稳妥。但底层逻辑是通的：SKILL.md 就是一份结构化的、模型无关的能力描述，任何能读取项目文件并遵循指令的 agent，都可以消费它。

5. 常见问题与排查实录：我踩过的坑，你直接绕开

5.1 安装失败、技能目录没生成

遇到最多的问题就是/plugin install superpowers@latest后报错，或者命令跑完但.claude/skills目录没出现。

先列排查顺序：

1. 确认 Claude Code 版本够新，claude --version查看版本号，低于官方要求就升级。插件机制是老版本没有的能力。
2. 确认网络能正常访问 GitHub。superpowers安装时要从 GitHub 拉取资源，网络不通会静默失败。
3. 确认当前工作目录有写入权限。.claude/skills要写进项目目录，如果项目目录是 root 所有，你的普通用户写不进去，命令会报权限错误（或者装作成功但没生成文件）。
4. 直接在当前对话里输入/plugin，查看插件列表里superpowers的状态。如果是installed但没生成技能文件，手动把仓库里skills/目录复制到项目.claude/skills/也能救回来。

我碰到过一次很诡异的情况：插件显示已安装，但技能目录生成到了用户全局目录而不是项目目录。原因是插件初始化时询问目录，我手滑选了~/.claude/skills。这不是 bug，是选项搞错了。如果你希望技能跟着项目走（推荐，团队协作时别人 clone 项目就能用），初始化时一定要选择当前项目目录。

5.2 技能加载了但不生效，AI 不理技能指令

装好了、也确认技能文件被读入了，但 AI 就是不按技能流程走。这种情况我也遇到过几次，多半是下面几个原因：

• 技能文件里的触发条件和实际任务的措辞不匹配。比如技能定义里写的是"用户提出新功能需求时触发"，而你对话里说的是"帮我加个功能"，AI 可能判断相似度不够就不触发。解决办法是显式点名："用 TDD 技能实现这个功能"。
• 对话里已经堆积了太多无关上下文。技能是按需加载的，如果上下文窗口里塞满了闲聊和历史消息，AI 的关注点会分散，倾向于直接回答而不是走流程。解决方法是新开会话，把需求讲清楚再调用技能。
• 多个技能互相冲突。同时安装了brainstorming和某个第三方规划技能，两者都试图接管同一个任务，AI 可能会二选一或者混着用。遇到这种情况，建议停用第三方技能，只保留一套核心流程。

5.3 成本与控制：三个实测心得

技能系统会增加 token 消耗吗？会。每个技能文件被加载都要占用上下文，而且技能不只是在"用"的时候才读——AI 要扫描目录、判断是否触发，这些都会增加开销。但实测下来，日常开发中增加的 token 比例通常能控制在 10%~15% 以内，相对于它带来的减少返工的效果，完全划算。

控制成本的三个心得：

1. 冷热分离。把.claude/skills里常用的几个技能（debugging、TDD）留在项目里，不常用的技能单独建一个skills-archive目录，项目说明里告诉 AI"归档目录只在显式要求时查看"。这样日常扫描范围小，需要时又能拿出来用。
2. 精简技能文件内容。SKILL.md写得越精简，每次加载时 token 越省。社区里有些技能文件写得像论文，动辄几百行，实际生效的核心指令可能只有二三十行。我后来把自己的技能库做了一次瘦身，删了大量示例和背景说明，效果几乎不变，token 开销下来了。
3. 会话按任务切分。一个会话只做一个任务，做完就结束新开会话。这样技能不会反复被加载，AI 也能保持对技能流程的专注度。

5.4 其他容易忽略的细节

• 技能文件可以改。SKILL.md不是保险箱里的死文件，你觉得某个步骤不合理、某个指令表述不清晰，完全可以自己改。我通常会把团队规范直接写进技能文件里，让 AI 自动遵守，比自己每次口头强调有用得多。
• 版本要关注。superpowers迭代很快，几天不看就会多出好几个新技能、修改既有技能的结构。如果你发现自己的 AI 行为突然变了（比如以前触发 TDD 现在不触发了），大概率是技能文件随更新变化了，去git log看一下技能目录的变更记录就明白了。
• 不要迷信技能数量。核心技能就那么几个，真正改变开发体验的是你用它们跑过多少真实任务、迭代过多少次技能内容。技能装得多但用不起来，远不如把三五个技能打磨到顺手。

最后分享一个小技巧

我自己用superpowers时间长了，最深刻的体会是：它的价值不在那几十个现成技能，而在于帮你建立了一个"把工作方法给 AI 用"的思维。现在我给自己的所有 AI 项目都会单独写SKILL.md，内容也不复杂——就三步：这个任务什么时候会触发、按什么顺序做、做完怎么算完成。哪怕项目不装superpowers，这份文件放到.claude/skills下面，AI 也能在关键时刻按我的思路走。

如果你准备入坑，我建议第一周只做一件事：把systematic-debugging和test-driven-development用熟。你的 AI 会从"给啥写啥、报错瞎猜"变成"先复现、先写失败测试、再动手修"的流程化状态，这个转变本身就是质的飞跃。用顺手了之后，再慢慢把 brainstorming、code review 这些配套技能加进去，你会发现整个研发节奏都变了。