企业官网建设流程全解析

1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去之前我以为又是个套壳工具，翻完之后发现不太一样——它试图回答一个很具体的问题：当 Claude Code、Codex CLI 这类命令行 AI 编程助手已经能读写文件、执行终端命令之后，怎么让它们稳定地按一套软件工程方法论干活，而不是每次都要靠人反复叮嘱。

这个问题的痛点，只要你用过 Claude Code 或者 Codex CLI 就懂。默认状态下，这些工具确实能帮你改代码、跑测试、提交 commit，但它们的“行为模式”是散的。你让它修个 bug，它可能直接上手改，改完也不跑测试；你让它加个功能，它可能一口气写三百行，中间不跟你确认任何设计决策。每次开新会话，之前建立的规矩全部清零，你得重新交代一遍“先写测试再改代码”“改完要跑 lint”“提交信息用 conventional commits”。

superpowers 这个项目的核心思路，是把这些“规矩”从人的口头指令里抽出来，变成一套可复用、可组合、可版本管理的agentic skills。你可以把它理解成给 AI 编程助手装的一套“行为操作系统”——每个 skill 是一个独立的能力单元，有明确的触发条件、执行步骤和验收标准，多个 skill 可以串成一条工作流。它本质上是一套software development methodology的工程化落地，只不过执行者从人变成了 AI agent。

适合谁来参考这套东西？三类人最直接受益。第一类是已经在日常开发里重度使用 Claude Code 或 Codex CLI 的工程师，想让这些工具的输出质量更稳定；第二类是在团队里推动 AI 辅助开发规范的 tech lead，需要一套可复制的方法论而不是个人经验；第三类是对 agentic 工作流本身感兴趣、想自己搭一套类似体系的开发者。哪怕你只是刚装好 Claude Code、还在摸索/compact和/resume怎么用，理解 superpowers 的设计思路也能帮你少走很多弯路。

下面我会从设计思路、核心机制、实操落地、常见坑四个层面，把这套框架拆开讲清楚。涉及具体配置的地方，我会给出可直接抄的参数和步骤；涉及设计取舍的地方，我会解释为什么这么选而不是那么选。

2. 核心设计思路拆解：为什么是 skills 而不是 prompts

2.1 从“一次性指令”到“可组合能力单元”的转变

大部分人用 Claude Code 的方式，是在对话里直接下指令：“帮我重构这个函数”“给这个模块加个测试”。这种模式的问题在于，指令是一次性的，用完就没了。下次遇到类似任务，你得重新描述一遍需求，而且描述的质量直接决定输出质量。更麻烦的是，当任务变复杂、需要多个步骤串联时，纯靠对话很难保证每一步都按你期望的顺序和标准执行。

superpowers 的做法是把每个高频操作抽象成一个skill。一个 skill 通常包含几个要素：触发条件（什么情况下该用这个 skill）、输入（需要哪些上下文信息）、执行步骤（具体做什么，按什么顺序）、输出（产出什么，格式是什么）、验收标准（怎么判断做完了）。这跟传统软件工程里的“函数”概念很像——有明确的签名、有确定的输入输出、可以被其他函数调用。

我举个具体例子。假设你有一个 skill 叫write-test-first，它的定义大概是这样的：当用户要求新增功能或修复 bug 时触发；输入是需求描述和相关代码文件；执行步骤是先分析需求边界，再写一个会失败的测试用例，然后运行测试确认它确实失败，最后才进入实现阶段；输出是一个失败的测试文件加上测试运行结果；验收标准是测试确实因为功能缺失而失败，而不是因为语法错误。

这个 skill 一旦定义好，你在任何会话里都可以直接调用它，不需要每次重新解释“先写测试”这件事。而且因为它是独立文件，你可以用 git 管理它的版本，团队里其他人也能直接复用。

2.2 为什么选择“框架”而不是“插件”或“脚本”

这里有个关键的设计取舍值得说清楚。实现类似效果其实有三条路：写插件、写脚本、做框架。superpowers 选了第三条，我认为这个选择是对的，理由有三。

第一，插件和脚本通常是绑定特定工具的。你给 Claude Code 写个插件，换到 Codex CLI 就用不了。而 superpowers 定义的是 skill 的抽象结构，理论上可以适配任何支持自定义指令的 agent 工具。热词里同时出现 Claude Code 和 Codex CLI，说明大家确实有跨工具复用的需求。

第二，脚本擅长处理确定性任务，但 AI 编程的场景里充满了需要判断的环节。“这个改动要不要跑全量测试”“这个重构会不会影响其他模块”，这些判断需要 agent 自己根据上下文做决策，而不是脚本里写死的 if-else。框架提供的是决策的脚手架，具体判断留给 agent。

第三，框架天然支持组合和扩展。你可以把write-test-first和run-lint和commit-conventional串成一条完整的提交流水线，也可以只调用其中某一个。这种灵活性是插件和脚本很难提供的。

2.3 与 Claude Code 原生能力的边界划分

需要明确一点：superpowers 不是要替代 Claude Code 或 Codex CLI 的原生能力，而是在它们之上加一层方法论约束。Claude Code 本身已经能读写文件、执行命令、管理会话（/compact压缩上下文、/model切换模型、/resume恢复会话），这些底层能力是 superpowers 运行的基础。

superpowers 负责的是“什么时候该做什么、按什么标准做”。比如 Claude Code 能执行npm test，但“改完代码必须跑测试”这条规矩是 superpowers 加的。Claude Code 能调用git commit，但“提交信息必须符合 conventional commits 格式”这条约束也是 superpowers 加的。

这种分层设计的好处是，底层工具升级时，上层的方法论不用大改。Claude Code 从某个版本升级到另一个版本，命令可能有变化，但 skill 里定义的“先测试后实现”这个原则不会变。

3. 核心机制与实操要点：skill 的定义、加载与执行

3.1 skill 的文件结构与字段说明

一个标准的 skill 定义文件，通常包含以下几个部分。我用一个实际可用的例子来说明，这个 skill 叫safe-refactor，用于安全地重构代码。

name: safe-refactor version: 1.0.0 trigger: - user_request_contains: ["重构", "refactor", "提取", "extract"] - file_type: [".js", ".ts", ".py", ".go"] inputs: - target_file: 需要重构的文件路径 - refactor_goal: 重构目标描述 steps: - id: analyze action: 分析目标文件的依赖关系和调用方 - id: snapshot action: 记录重构前的测试通过状态 - id: refactor action: 执行重构，每次只改一个逻辑单元 - id: verify action: 每步重构后运行相关测试 - id: report action: 输出重构前后的对比摘要 acceptance: - 所有原有测试仍然通过 - 没有新增 lint 错误 - 重构后的代码行数不超过原来的 120%

这个结构里，trigger决定了 skill 什么时候被激活，steps定义了执行顺序，acceptance是验收标准。注意acceptance里那条“代码行数不超过原来的 120%”——这是防止 agent 在重构时顺手加一堆新功能，把重构变成重写。

提示：skill 的 version 字段很重要。当你修改了 skill 的逻辑，一定要升版本号。否则团队里有人用旧版、有人用新版，行为不一致会很难排查。

3.2 skill 的加载机制与优先级

skill 文件放在哪里、怎么被 agent 发现，这是实操中第一个要解决的问题。常见的做法是在项目根目录建一个.skills/目录，所有 skill 文件放里面。agent 启动时扫描这个目录，把所有 skill 加载到上下文里。

但这里有个坑：如果 skill 太多，全部加载会占用大量上下文窗口，导致 agent 处理实际任务时“内存不足”。我的经验是，按需加载比全量加载更实用。具体做法是在项目根目录放一个skills.index文件，列出所有可用 skill 的名称和一句话描述，agent 先读这个索引，需要哪个再加载哪个。

优先级方面，我建议按这个顺序：项目级 skill > 用户级 skill > 内置 skill。项目级的放在项目.skills/目录，用户级的放在~/.config/skills/目录。这样同一个 skill 名称，项目里的定义会覆盖全局的，方便针对特定项目做定制。

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

触发条件写得好不好，直接决定 skill 会不会在该用的时候用上、不该用的时候乱用。我见过最常见的两个误区。

第一个误区是触发条件写得太宽泛。比如有个 skill 的触发条件是“用户提到测试”，结果用户说“这个测试环境怎么配置”，agent 也去调用write-test-first，这就跑偏了。正确的做法是加上更具体的限定，比如“用户要求新增功能或修复 bug 且涉及代码修改”。

第二个误区是触发条件写得太死。比如只匹配“重构”这个词，用户说“优化一下这段代码”就触发不了。我的做法是同时配置关键词匹配和语义匹配，关键词覆盖常见说法，语义匹配兜底。Claude Code 和 Codex CLI 都支持一定程度的语义理解，可以利用这个能力。

还有一个实操技巧：给每个 skill 加一个negative_trigger字段，明确列出什么情况下不要用这个 skill。比如safe-refactor的 negative trigger 可以写“用户明确要求重写而非重构”“目标文件没有测试覆盖”。这能显著减少误触发。

3.4 执行过程中的状态管理

skill 执行到一半失败了怎么办？这是很多人忽略的问题。比如safe-refactor执行到第三步，测试挂了，这时候是回滚还是继续？

我的做法是在 skill 定义里加一个on_failure字段，指定失败时的行为。可选值有三个：rollback（回滚到执行前状态）、pause（暂停并询问用户）、continue（记录问题继续执行）。对于重构类 skill，我一般设成rollback，因为半成品重构比不重构更危险。对于文档生成类 skill，设成continue更合适，因为部分产出也有价值。

状态管理还涉及一个细节：skill 执行过程中的中间状态存在哪里。如果存在内存里，会话中断就丢了。我建议把关键中间状态写到项目目录下的.skills-state/文件夹里，每个 skill 执行实例一个文件。这样即使会话断了，用/resume恢复后还能接着跑。

4. 完整实操流程：从零搭一套可用的 skill 体系

4.1 环境准备与工具安装

先把基础环境搭好。假设你在 Ubuntu 或者 macOS 上，Windows 用户建议用 WSL，因为 Claude Code 和 Codex CLI 在原生 Windows 上的兼容性偶尔会有问题（热词里那条“由于与64位版本的windows不兼容”就是这类问题）。

Claude Code 的安装，官方推荐的方式是通过 npm 全局安装：

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

装完之后运行claude命令，按提示完成账号注册和登录。如果你在 VS Code 里用，可以装 Claude Code for VS Code 插件，在插件设置里配置好路径就能直接在编辑器里调用。

Codex CLI 的安装类似：

npm install -g @openai/codex-cli

装完后用codex命令启动。Codex CLI 的常用命令包括/compact（压缩上下文）、/model（切换模型）、/resume（恢复会话），这些在实操中会频繁用到。

注意：如果你在安装或登录时遇到“your organization has disabled claude subscription access”这类提示，通常是账号权限问题，需要检查你的订阅类型是否支持 Claude Code。另外“note: claude code might not be available in your country”这类提示，说明当前网络环境不在支持范围内，这个需要自行解决，本文不展开。

4.2 创建第一个 skill：从 write-test-first 开始

环境好了之后，先建项目目录结构：

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

然后创建第一个 skill 文件.skills/write-test-first.yaml：

name: write-test-first version: 1.0.0 description: 在实现任何新功能或修复 bug 之前，先写一个会失败的测试 trigger: keywords: ["新增功能", "修复bug", "add feature", "fix bug"] file_types: [".js", ".ts", ".py", ".go", ".java"] negative_trigger: - "用户明确说不需要测试" - "目标文件是配置文件或文档" inputs: - requirement: 需求描述 - target_module: 目标模块路径 steps: - id: analyze_requirement action: 分析需求的输入、输出和边界条件 output: 需求分析摘要 - id: write_test action: 编写一个测试用例，覆盖核心场景 output: 测试文件 - id: run_test action: 运行测试，确认它失败 command: "npm test -- --grep '新测试名称'" - id: confirm_failure action: 检查失败原因是否为功能缺失 acceptance: - 测试确实运行了 - 测试失败原因是功能未实现，而非语法错误 - 测试用例覆盖了至少一个边界条件 on_failure: pause

这个 skill 的关键在于confirm_failure这一步。很多人写测试驱动开发，写完测试发现它失败了就以为对了，但其实失败原因可能是拼写错误、导入路径不对，而不是功能缺失。这一步就是专门堵这个漏洞的。

4.3 把 skill 串成工作流

单个 skill 有用，但真正提升效率的是把多个 skill 串起来。比如一条完整的“功能开发流水线”可以是这样的：

1. write-test-first：先写失败测试
2. implement-minimal：写最少的代码让测试通过
3. run-lint：跑 lint 检查
4. safe-refactor：如果代码有重复，做一次小重构
5. commit-conventional：按规范提交

在 superpowers 里，这种串联可以通过一个workflow文件定义：

name: feature-development version: 1.0.0 skills: - write-test-first - implement-minimal - run-lint - safe-refactor - commit-conventional execution: sequential stop_on_failure: true

stop_on_failure: true意味着任何一步失败，整条流水线暂停，等人工介入。这个设置对生产代码很重要，避免一个环节出问题后面全乱套。

4.4 在 Claude Code 和 Codex CLI 里调用 skill

skill 定义好了，怎么让 agent 用上？在 Claude Code 里，你可以在项目根目录的CLAUDE.md文件里声明 skill 目录：

## Skills 本项目使用 superpowers skill 体系，skill 定义位于 `.skills/` 目录。 执行任务前先读取 `.skills/skills.index`，根据任务类型加载对应 skill。

然后在对话里直接说“用 feature-development 流程开发这个功能”，Claude Code 就会去加载对应的 workflow。

Codex CLI 的配置类似，在项目根目录的codex.config.json里加：

{ "skills": { "directory": ".skills", "autoLoad": false, "indexFile": "skills.index" } }

autoLoad: false是我强烈建议的设置。自动加载所有 skill 会吃掉大量上下文，手动按需加载虽然多一步操作，但实际体验更好。

4.5 参数计算与选择：上下文预算怎么分配

这里说一个很多人忽略的实操细节：上下文窗口的预算分配。Claude Code 和 Codex CLI 的上下文窗口是有限的，skill 定义、代码文件、对话历史、工具输出都要占空间。如果 skill 定义写得太啰嗦，留给实际代码的空间就少了。

我的经验值是：skill 定义本身控制在 500 token 以内，workflow 定义控制在 300 token 以内，留给代码和对话的空间至少保留 60%。如果发现 agent 经常“忘记”前面的指令，多半是上下文被 skill 定义挤爆了，这时候要么精简 skill，要么用/compact压缩历史。

具体怎么算？一个中等复杂度的 skill，YAML 大概 40 行，每行平均 10 个 token，就是 400 token。十个 skill 全加载就是 4000 token。Claude Code 的上下文窗口按 200K token 算，4000 token 占 2%，看起来不多，但加上代码文件（一个中等项目动辄几万 token）和对话历史，很快就紧张了。所以按需加载不是可选项，是必选项。

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

5.1 skill 不触发或误触发怎么办

这是最高频的问题。排查思路按这个顺序走：

第一步，检查 skill 文件是否被正确加载。在 Claude Code 里输入/skills list（如果支持的话），或者直接问 agent“你现在加载了哪些 skill”。如果列表里没有你的 skill，说明加载环节有问题，检查目录路径和索引文件。

第二步，检查触发条件。把触发条件里的关键词和你的实际输入对比，看是否匹配。如果用的是语义匹配，试着换几种说法。我遇到过用户说“帮我改一下这个函数”，触发条件里写的是“修改函数”，语义上应该匹配但实际没触发，后来发现是 skill 的negative_trigger里有一条“用户没有明确说重构”误伤了。

第三步，检查优先级。如果项目级和用户级有同名 skill，确认加载的是哪个版本。可以在 skill 定义里加一个debug: true字段，执行时打印实际加载的 skill 来源。

误触发的问题，八成是触发条件太宽泛。我的建议是给每个 skill 加一个“最小匹配”原则：至少满足两个条件才触发。比如既要关键词匹配，又要文件类型匹配。

5.2 skill 执行到一半卡住或报错

常见原因有三个。第一个是命令执行失败，比如npm test因为依赖没装而报错。这种情况在on_failure设为pause时会暂停，你可以手动装完依赖再用/resume继续。

第二个是 agent 在某个步骤上“想太多”，反复修改同一个文件。这通常是因为验收标准不够明确，agent 不确定什么时候算做完。解决办法是把acceptance写得更具体，比如把“测试通过”改成“运行npm test后退出码为 0 且输出中没有 FAIL 字样”。

第三个是上下文溢出。执行到后面步骤时，前面的工具输出把上下文占满了，agent 开始丢指令。这时候用/compact压缩一下，或者把不必要的历史清掉。

5.3 跨工具复用时的不兼容问题

Claude Code 和 Codex CLI 对 skill 的支持程度不完全一样。Claude Code 对 YAML 格式的 skill 支持较好，Codex CLI 可能更偏好 JSON。我的做法是 skill 定义用 YAML 写，然后写一个转换脚本生成 JSON 版本。这样维护一份源文件，两边都能用。

另一个不兼容点是命令语法。Claude Code 里执行终端命令的方式和 Codex CLI 略有不同，skill 里的command字段需要做适配。我一般把命令写成变量形式，在加载时根据当前工具替换。

5.4 常见问题速查表

5.5 几个踩过坑才明白的经验

第一个经验：不要一开始就写很多 skill。我最初一口气定义了十几个，结果维护成本极高，而且很多 skill 之间逻辑重叠，agent 经常不知道该用哪个。后来砍到五个核心 skill，反而效果好。建议从两三个最高频的场景开始，用顺了再扩展。

第二个经验：skill 的验收标准要可执行，不要写“代码质量好”这种主观描述。什么叫质量好？agent 理解不了。要写成“没有新增 lint 错误”“圈复杂度不超过 10”“函数长度不超过 50 行”这种可以自动检查的指标。

第三个经验：定期回顾 skill 的使用记录。我会每周看一次.skills-state/里的执行日志，统计哪些 skill 用得多、哪些几乎没用、哪些经常失败。用得少的考虑删掉，经常失败的说明定义有问题需要改。这个习惯让我的 skill 体系一直保持精简有效。

第四个经验：skill 的命名要一致。我见过有人用write-test-first，有人用test_first，有人用先写测试，混在一起很难管理。统一用英文小写加连字符，团队协作时尤其重要。

6. 进阶玩法：把 skill 体系和本地模型、第三方 API 结合

6.1 用本地模型跑 skill 的可行性

热词里有人问“claude code 调用 lmstudio 的本地模型”，这确实是个有意思的方向。把 skill 体系和本地模型结合，好处是数据不出本地、成本低、可以离线用。但要注意，本地模型对复杂 skill 的理解能力通常不如云端大模型，尤其是涉及多步推理的 skill。

我的实测经验是，本地模型适合跑结构简单、步骤明确的 skill，比如run-lint、commit-conventional这种。涉及需求分析、重构决策的 skill，还是用云端模型更稳。一个折中方案是混合使用：简单 skill 走本地模型，复杂 skill 走云端。

配置上，在 Claude Code 里可以通过环境变量指定模型端点。具体做法是设置ANTHROPIC_BASE_URL指向本地模型的 API 地址，然后/model命令切换。LM Studio 启动后默认在http://localhost:1234提供兼容 API，配置好就能用。

6.2 通过第三方 API 接入其他模型

热词里提到“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”，这是另一个常见需求。cc switch 这类工具的作用是在不同模型提供商之间切换，让 Claude Code 或 Codex CLI 能调用非默认的模型。

实操上，你需要先拿到对应模型的 API key，然后在 cc switch 的配置里添加提供商信息。配置好之后，用/model命令就能切换。这里有个细节：不同模型对 skill 定义格式的兼容性不一样，切换后要重新测试一遍核心 skill 是否正常工作。

注意：使用第三方 API 时，skill 里涉及代码上传的步骤要格外小心。确认 API 提供商的数据处理政策，避免把敏感代码传到不可控的地方。

6.3 skill 体系的团队协作与版本管理

一个人用 skill 和团队用 skill，复杂度差一个量级。团队场景下，我建议把.skills/目录纳入 git 管理，每个 skill 的修改走 pull request 流程。skill 的 version 字段和 git tag 对应起来，方便追溯。

另外建议建一个SKILLS_CHANGELOG.md，记录每个 skill 的变更历史和变更原因。比如“v1.1.0 把验收标准从‘测试通过’改成‘测试通过且覆盖率不低于 80%’，因为发现 agent 经常写只覆盖一个场景的测试”。这种记录在团队协作时能省很多沟通成本。

6.4 和其他工具链的集成思路

superpowers 的 skill 体系理论上可以和任何支持自定义指令的 AI 编程工具集成。除了 Claude Code 和 Codex CLI，热词里还提到“codex cli remotion”，说明有人在做视频生成相关的集成。思路是一样的：把 remotion 的常用操作抽象成 skill，让 agent 按规范生成视频代码。

飞书连接 Claude Code 这类需求，本质上是把 skill 的执行入口从命令行扩展到聊天工具。做法是写一个中间层，接收飞书消息，转成 Claude Code 能理解的指令，再把结果返回飞书。skill 体系在这个场景下的价值是保证无论从哪个入口触发，执行标准都是一致的。

7. 我个人的一些实操体会

这套东西我用了大概三个月，最大的感受是：skill 的价值不在于让 agent 更聪明，而在于让 agent 更可预测。以前用 Claude Code，同样的需求说两遍可能得到两个不同风格的结果，现在有了 skill 约束，输出质量稳定多了。

另一个体会是，写 skill 的过程其实是在逼自己把“我觉得应该这样做”的模糊直觉，转化成明确的、可执行的步骤。这个转化过程本身就很有价值，哪怕你最后不用 AI 工具，这套方法论对带人、对写文档都有帮助。

最后分享一个小技巧：如果你不确定某个 skill 该怎么写，可以先手动做一遍这个任务，把每一步的操作和判断标准记下来，然后直接把这些记录整理成 skill 定义。这比凭空想要靠谱得多。我最初的几个 skill 就是这么来的，效果比后来刻意设计的还好。