企业官网建设流程全解析

1. 从“superpowers”说起：这套技能框架到底在解决什么问题

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏模组，或者某个插件市场的营销噱头。但如果你最近在折腾 Claude Code 或者 Codex CLI 这类终端里的 AI 编程助手，大概率已经在各种社区里刷到过它。简单说，superpowers 是一套面向 AI 编程代理的技能框架（agentic skills framework），它把“怎么让 AI 更靠谱地写代码”这件事，从零散的提示词技巧，沉淀成了一套可复用、可组合、可版本管理的技能包。

我自己的理解是：它更像一套“软件开发方法论”的落地载体。过去我们用 AI 写代码，靠的是每次现编一段提示词，效果全看当天状态和模型心情。而 superpowers 的思路是，把常见的开发动作——比如读代码、改 bug、写测试、做代码审查、生成提交信息——拆成一个个独立的 skill（技能），每个 skill 有明确的触发条件、输入输出和执行步骤。AI 代理在干活时，不再是“一把梭”，而是按需加载对应的技能，像人一样先看再动手。

这套东西能火起来，跟 Claude Code 和 Codex CLI 的普及有直接关系。这两个工具本质上都是把大模型塞进终端，让它直接操作你的文件系统、跑命令、改代码。能力很强，但风险也大——你让它改个函数，它可能顺手重构了整个模块。superpowers 这类框架的价值就在于，给这种“野生”的代理行为套上一层结构化的约束，让它的每一步操作都有章可循。

适合谁来参考？我觉得三类人最该看看：一是已经在用 Claude Code 或 Codex CLI，但总觉得输出不稳定、想提升可控性的开发者；二是团队里想把 AI 编程流程标准化，让不同人用 AI 写出来的代码风格和质量尽量一致的技术负责人；三是对 agentic skills 这个概念好奇，想自己动手搭一套技能体系的技术爱好者。哪怕你只是刚装好 Claude Code，还没搞明白 skill 目录该放哪，这篇文章里的安装、配置和踩坑记录也能直接拿去用。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 从提示词工程到技能工程的转变

早两年大家聊 AI 编程，张口闭口都是“提示词工程”。但实际用下来你会发现，提示词这东西太脆了。同一个提示词，今天跑出来是满分代码，明天模型更新一版，输出就变了味。而且提示词是扁平的，你很难把“先分析需求、再查现有代码、然后写实现、最后补测试”这种多步骤流程，塞进一段自然语言里还不让模型漏步骤。

superpowers 代表的技能工程思路，核心变化在于把隐式知识显式化。一个 skill 通常包含几个固定部分：名称、描述、触发条件、执行指令、以及可选的示例。它不依赖模型“悟”，而是把该做什么、按什么顺序做、做到什么程度算完，全部写死在技能文件里。模型要做的只是匹配和调用，而不是即兴发挥。

这个转变带来的最大好处是可测试。你可以单独测一个 skill 在给定输入下是否稳定输出预期结果，而不是每次都要端到端跑一遍完整对话。对于团队协作来说，技能文件可以进 Git，可以 code review，可以像管理代码一样管理 AI 的行为规范。

2.2 技能框架的组成结构

一套典型的 superpowers 风格框架，目录结构大致长这样：

skills/ code-review/ SKILL.md examples/ write-tests/ SKILL.md refactor/ SKILL.md commit-message/ SKILL.md

每个SKILL.md是核心，里面用 Markdown 写清楚这个技能干什么、什么时候用、具体步骤是什么。有些实现还会带examples/目录，放几个输入输出样例，帮助模型理解边界情况。

为什么用 Markdown 而不是 JSON 或 YAML？我的经验是，Markdown 对模型更友好。模型在训练时见过海量 Markdown 文档，对标题层级、列表、代码块的理解非常自然。你用 JSON 写指令，模型也能读，但容易把结构当成数据而不是指令，执行时反而容易跑偏。Markdown 的“文档感”会让模型更倾向于把它当作操作手册来遵循。

2.3 与 Claude Code、Codex CLI 的集成逻辑

Claude Code 和 Codex CLI 都支持某种形式的“技能”或“自定义指令”加载。以 Claude Code 为例，它会在项目目录下寻找特定文件夹（常见的是.claude/skills/或用户主目录下的配置目录），把里面的技能文件读进上下文。当你的对话触发了某个技能描述里的关键词或场景，代理就会自动加载对应技能，按里面的步骤执行。

Codex CLI 的机制类似，但配置路径和加载优先级可能不同。这里有个关键点：技能不是越多越好。我试过一次性塞进去二十多个技能，结果模型在匹配时经常选错，或者把多个技能的步骤混在一起执行。后来精简到八个核心技能，命中率和执行质量都明显提升。所以设计技能框架时，宁可少而精，每个技能覆盖一个明确的开发动作，不要试图做一个“万能技能”。

3. 安装与配置实操：Claude Code 和 Codex CLI 两条路线

3.1 Claude Code 的安装与技能目录配置

Claude Code 的安装方式取决于你的操作系统。在 macOS 和 Linux 上，通常通过包管理器或官方安装脚本完成。Ubuntu 用户可以直接用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

装完之后，在终端输入claude应该能进入交互界面。如果提示找不到命令，检查 npm 全局 bin 目录是否在 PATH 里。Windows 用户建议在 WSL2 环境下操作，原生 Windows 的支持虽然有了，但路径和权限问题会多不少。

技能目录的配置是重点。Claude Code 默认会读取项目根目录下的.claude/文件夹。你可以在里面建一个skills/子目录，把每个技能放成一个独立的 Markdown 文件。比如：

your-project/ .claude/ skills/ code-review.md write-tests.md refactor.md

然后在code-review.md里写清楚技能定义。一个最简单的技能文件长这样：

# Code Review Skill ## When to use 当用户要求审查代码、检查代码质量、或提到 "review" 时触发。 ## Steps 1. 读取用户指定的文件或最近修改的文件 2. 检查以下方面：命名规范、错误处理、边界条件、性能隐患 3. 按严重程度分级列出问题：critical / major / minor 4. 对每个问题给出具体修改建议，附上代码示例 ## Output format 用 Markdown 表格列出问题，包含文件、行号、级别、描述、建议。

这里有个实操心得：技能文件里的步骤要用祈使句，不要用描述句。写“检查错误处理”比写“应该检查错误处理”效果好得多。模型对指令式语言的遵循度明显更高。

3.2 Codex CLI 的安装与技能加载

Codex CLI 的安装路径不太一样。它通常是作为独立二进制或者通过特定包管理器分发。安装完成后，你需要确认它的配置目录位置。常见的是~/.codex/或项目下的.codex/。

Codex CLI 加载技能的方式，据我实测，更倾向于读取一个集中的配置文件，而不是散落的 Markdown。你可以在配置里指定技能目录，或者直接把技能内容写进配置的skills字段。具体格式参考官方文档，但核心逻辑和 Claude Code 一致：定义触发条件、执行步骤、输出要求。

如果你遇到unable to locate the codex cli binary or required runtime components这类报错，八成是安装不完整或者环境变量没配好。排查顺序是：先确认二进制文件确实存在，再检查 PATH，最后看运行时依赖（比如 Node 版本、Python 版本）是否满足要求。Windows 上还常见一个问题：安装路径里有空格或中文，导致 CLI 启动失败。把安装目录换成纯英文无空格的路径，基本能解决。

3.3 两个工具的技能互通策略

Claude Code 和 Codex CLI 的技能格式不完全一样，但核心内容可以复用。我的做法是维护一份“技能源文件”，用最通用的 Markdown 写，然后写个小脚本转换成各自需要的格式。这样改一处，两边都能更新。

如果你只用一个工具，那就没必要折腾互通。但如果你像我一样，有时候用 Claude Code 做探索性开发，有时候用 Codex CLI 跑批量任务，那统一技能定义能省很多事。关键是保持技能名称和触发条件一致，避免在两边产生行为差异。

4. 技能设计与编写：从“能用”到“好用”的关键细节

4.1 触发条件的写法与常见误区

触发条件是技能框架里最容易被忽视、但影响最大的部分。写得太宽，技能会被频繁误触发；写得太窄，该用的时候又匹配不上。

我踩过的坑：早期写了一个refactor技能，触发条件写的是“当用户提到重构时”。结果模型把“重构一下这个变量名”也当成大重构来处理，加载了整套重构流程，输出了一堆不必要的分析。后来改成“当用户要求进行结构性代码重构、涉及多个文件或模块的调整时”，精准度立刻上来了。

好的触发条件通常包含三个要素：动作词（review、test、refactor、commit）、对象词（file、function、module、PR）、场景限定（when user asks for、before committing、after code change）。三者组合起来，既能覆盖目标场景，又不会过度泛化。

4.2 步骤拆解的粒度控制

步骤拆得太粗，模型会自由发挥；拆得太细，又显得死板，遇到稍微不同的情况就卡住。我的经验是，每个技能控制在 5 到 9 个步骤，每个步骤是一个明确的动作，但不要规定具体用什么命令或什么函数。

举个例子，write-tests技能的步骤可以这样写：

1. 识别待测试的函数或模块
2. 分析输入参数和预期输出
3. 列出正常路径、边界条件、异常路径
4. 为每类情况生成至少一个测试用例
5. 运行测试并确认全部通过
6. 如果测试失败，分析是测试问题还是实现问题

这里没有写“用 pytest”或“用 jest”，因为具体框架应该由项目上下文决定。模型会自己去看项目里已有的测试文件，推断出该用什么。如果你在技能里写死了框架，换个项目就不好使了。

4.3 输出格式的约束技巧

输出格式约束是保证结果可用的关键。没有格式约束，模型可能给你一段散文式的分析；有了格式约束，你才能直接把输出贴进 issue 或者 PR 评论里。

我常用的格式约束有三种：表格用于对比和清单，代码块用于具体修改建议，分级列表用于按优先级排列的问题。在技能文件里，直接给出格式模板，模型会照着填。比如：

## Output format | 文件 | 行号 | 级别 | 问题 | 建议 | |------|------|------|------|------| | ... | ... | critical/major/minor | ... | ... |

实测下来，给了模板之后，输出的结构一致性提升非常明显。哪怕模型偶尔填错内容，至少格式是对的，后续处理起来方便很多。

5. 实操全流程：从零搭一套可用的技能体系

5.1 环境准备与目录初始化

假设你已经在 Ubuntu 上装好了 Claude Code，现在要从零搭一套技能体系。第一步是建目录：

mkdir -p ~/my-project/.claude/skills cd ~/my-project

然后确认 Claude Code 能识别这个目录。启动claude，输入/skills或者类似的查看命令（不同版本命令可能不同），看它是否列出了你放在里面的技能文件。如果没列出来，检查文件扩展名是不是.md，以及文件是否有读取权限。

Codex CLI 这边，先确认配置文件位置。通常在~/.codex/config.toml或项目下的.codex/config.toml。在里面加上技能目录路径：

[skills] directory = ".codex/skills"

然后同样建目录、放技能文件。两个工具可以共用一套技能源文件，只是目录位置不同。

5.2 编写第一个技能：代码审查

拿code-review开刀，因为它的使用频率最高，效果也最直观。在.claude/skills/code-review.md里写入：

# Code Review ## Trigger 当用户要求审查代码、检查代码质量、review 文件、或提到 "看看这段代码有没有问题" 时触发。 ## Steps 1. 确定审查范围：用户指定的文件，或最近一次 git diff 涉及的文件 2. 逐个文件阅读，重点关注：命名清晰度、错误处理完整性、边界条件覆盖、潜在性能问题、安全风险 3. 对每个发现的问题，判断严重级别：critical（会导致错误或安全问题）、major（影响可维护性或性能）、minor（风格或小改进） 4. 给出具体修改建议，附上修改后的代码片段 5. 如果整体质量良好，也要明确指出做得好的地方 ## Output 用表格列出问题，按严重级别排序。最后给出一句总体评价。

写完之后，在 Claude Code 里打开一个项目文件，输入“帮我 review 一下这个文件”，看它是否自动加载了技能并按步骤执行。如果它没加载，检查触发条件里的关键词是否和你输入的内容匹配。

5.3 技能组合与工作流串联

单个技能好用之后，下一步是把它们串成工作流。比如一个典型的“改 bug”流程：先code-review定位问题，再refactor做修改，然后write-tests补测试，最后commit-message生成提交信息。

你可以在技能文件里写“前置技能”和“后置技能”字段，让模型知道执行完当前技能后该接哪个。或者更简单的方式：在对话里显式引导——“先用 code-review 看一下，然后根据结果决定要不要 refactor”。模型会按顺序加载对应技能。

我实测下来，串联工作流时最大的问题是上下文膨胀。每个技能加载都会占用 token，串四五个技能之后，上下文可能就不够用了。解决办法是让每个技能的输出尽量精简，只保留关键结论，不要把中间过程全部留在上下文里。

5.4 版本管理与团队共享

技能文件一定要进 Git。我见过太多人把技能写在本地配置里，换台机器就没了，或者团队里每个人用的技能版本不一样，导致 AI 输出风格五花八门。

推荐的做法是：在项目根目录建.claude/skills/和.codex/skills/，把技能文件提交到仓库。然后在 README 里写清楚每个技能的作用和使用场景。新成员拉下代码，Claude Code 和 Codex CLI 自动就能用上统一的技能集。

如果技能需要频繁调整，可以单独开一个skills分支，改完测试通过再合并到主分支。这样既能快速迭代，又不会影响主分支的稳定性。

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

6.1 技能不生效的排查清单

技能写了但模型不加载，是最常见的问题。按以下顺序排查：

我遇到过一次，技能文件明明在正确目录，但就是不生效。后来发现是文件名里有个空格，模型在匹配时把空格当成了分隔符。改成下划线或连字符就好了。这种细节问题很隐蔽，但排查起来其实很快，关键是养成“先看文件系统，再看配置，最后看模型行为”的习惯。

6.2 Codex CLI 安装报错处理

unable to locate the codex cli binary or required runtime components这个报错，我在 Windows 和 Ubuntu 上都见过。Windows 上的典型原因是安装路径没加到 PATH，或者安装的是 32 位版本但系统是 64 位。Ubuntu 上则多半是 Node 版本太低，或者缺少某个系统库。

处理步骤：

1. 确认二进制文件存在：which codex或where codex
2. 如果找不到，手动把安装目录加到 PATH
3. 检查运行时依赖：node --version看是否满足最低要求
4. Ubuntu 上如果报库缺失，用ldd查看具体缺哪个，然后apt install补上
5. Windows 上如果路径有空格，把安装目录移到C:\tools\codex这类无空格路径

还有一个坑：如果你之前装过旧版本，升级时可能残留旧文件导致冲突。彻底卸载后重装，比直接覆盖安装靠谱。

6.3 技能冲突与优先级问题

当多个技能的触发条件有重叠时，模型可能同时加载多个技能，导致步骤混乱。比如refactor和code-review都可能被“看看这段代码”触发。

解决办法有两个：一是收紧触发条件，让每个技能的触发词尽量不重叠；二是设置优先级，在技能文件里加一个priority字段，数值高的优先加载。Claude Code 和 Codex CLI 对优先级的支持方式不同，但核心思路都是让模型在冲突时有个明确的取舍依据。

我的经验是，宁可多花十分钟把触发条件写精确，也不要依赖优先级机制。因为优先级是“事后补救”，而精确的触发条件是“事前预防”，后者更可靠。

6.4 上下文管理与性能优化

技能多了之后，每次对话都要加载一堆技能文件，token 消耗很快。优化手段有几个：

• 按需加载：只在触发时才加载技能，而不是启动时全部读入。Claude Code 默认就是按需加载，但如果你在配置里强制预加载，就会浪费 token。
• 精简技能内容：每个技能文件控制在 200 行以内，去掉冗余解释，只留核心步骤和格式要求。
• 定期清理：三个月没用过的技能，要么删掉，要么归档到单独目录，不要留在活跃技能集里。
• 使用摘要：如果技能内容确实很长，可以在文件开头写一段摘要，让模型先读摘要判断是否需要加载完整内容。

我现在的技能集保持在 6 到 8 个，每个文件平均 80 行左右。日常使用中，上下文占用很稳定，没有出现过因为技能太多导致响应变慢或截断的情况。

7. 进阶玩法：把技能框架用到非典型场景

7.1 嵌入式开发中的技能定制

有人可能觉得 superpowers 这类框架只适合 Web 开发，其实不然。我拿它做过 STM32 相关的代码辅助，效果也不错。关键是把技能里的通用步骤，替换成嵌入式场景特有的检查项。

比如code-review技能，在嵌入式场景下可以增加这些检查点：中断处理是否用了volatile、寄存器操作是否有位掩码错误、堆栈大小是否足够、是否有阻塞调用放在中断里。把这些写进技能文件，模型审查嵌入式代码时就会自动带上这些视角。

7.2 与外部工具链的集成

技能框架本身不限制你调用什么工具。你可以在技能步骤里写“运行make test并分析输出”，或者“调用eslint检查代码风格”。模型会执行这些命令，并根据输出决定下一步。

我试过把commit-message技能和 Git hooks 结合：每次 commit 前，hook 自动触发技能生成提交信息，然后让用户确认。这样既保证了提交信息的规范性，又不会打断开发节奏。Codex CLI 在这类自动化场景下表现更稳，因为它的非交互模式更适合脚本调用。

7.3 技能体系的持续迭代

技能体系不是搭完就完事了。随着项目演进和模型更新，你需要定期回顾技能效果。我的做法是每个月抽半小时，把最近用过的技能过一遍，看看哪些步骤经常被跳过、哪些输出格式不再适用、哪些触发条件需要调整。

迭代时遵循一个原则：小步快跑，每次只改一个技能。同时改多个技能，出了问题很难定位是哪个改动导致的。改完之后，用几个典型场景测一下，确认效果符合预期再提交。

8. 一些个人体会和实用建议

折腾 superpowers 这套东西大半年，最大的感受是：技能框架的价值不在于让 AI 变聪明，而在于让 AI 变稳定。模型本身的能力已经很强了，但它需要结构化的引导才能把能力用在正确的地方。技能就是那个引导结构。

另一个体会是，不要追求大而全的技能库。我见过有人整理了五十多个技能，结果日常真正用到的就五六个。与其花时间写一堆用不上的技能，不如把最常用的那几个打磨到极致。一个精准的code-review技能，比十个泛泛而谈的技能更有价值。

最后分享一个小技巧：在技能文件里加一个## Anti-patterns段落，写明这个技能不应该做什么。比如refactor技能里写“不要改变公共 API 的签名，除非用户明确要求”。这种负面约束能有效防止模型过度发挥，减少意外改动。实测下来，加了 anti-patterns 之后，技能执行的边界感明显更强，返工率也低了不少。