企业官网建设流程全解析

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

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了一句“想要安装 superpowers”，底下立刻有人接“你是说 Claude Code 那套 skills 框架吧”。聊了十几分钟我才反应过来，大家嘴里的 superpowers 并不是某个单独的软件，而是一套围绕agentic skills framework构建的软件开发方法论——它把 Claude Code、Codex CLI 这类命令行智能体当作“执行手”，把可复用的技能模块当作“招式库”，让一个原本只会聊天的模型，变成能真正动手改代码、跑命令、查文档的工程搭档。

这套东西的核心价值，用一句话概括：把“提示词工程”升级成“技能工程”。以前我们用 Claude Code 或者 Codex CLI，靠的是每次现写 prompt，写得好模型就干得好，写得烂就翻车。而 superpowers 的思路是，把常见任务（比如初始化项目、写测试、重构函数、生成提交信息）沉淀成一个个独立的 skill 文件，智能体在执行时按需加载，不用每次从零描述。这就像你带徒弟，不是每次口头教一遍，而是给他一本操作手册，遇到什么场景翻到哪一页。

适合谁来参考？三类人最该看：一是已经在用 Claude Code 或 Codex CLI，但总觉得“它怎么老是不按我想的来”的开发者；二是想把 AI 编程工具接进团队工作流，却不知道怎么标准化的技术负责人；三是刚接触 agentic 工具链，想找一个能落地的切入点的新手。这篇文章我会从框架设计思路、核心技能拆解、完整实操流程、常见坑排查四个维度，把 superpowers 这套方法论掰开揉碎讲清楚，中间会穿插 Claude Code 安装、Codex CLI 命令、VS Code 配置这些热搜里高频出现的实操细节。

提示：本文提到的所有工具和命令，均以官方公开文档和社区常见实践为准，涉及账号、订阅、地区可用性等问题请以你实际环境为准，本文不做任何绕过限制的讨论。

2. 框架整体设计与思路拆解：为什么是“技能”而不是“提示词”

2.1 从提示词堆砌到技能模块化的必然性

早期用 Claude Code 的人应该都有体会：你打开终端，输入claude，然后开始跟它对话。第一次让它“帮我写个 React 组件”，它写得不错；第二次让它“帮我写个带表单验证的 React 组件”，也还行；但到第十次，你发现每次都要重复描述项目结构、代码风格、测试框架、命名规范，累不说，还容易漏。这就是典型的提示词堆砌困境——所有上下文都靠你临时喂，模型没有稳定的“记忆锚点”。

superpowers 这套 agentic skills framework 的设计出发点，就是解决这个困境。它把“你希望智能体怎么做事”从对话里抽出来，写成结构化的 skill 文件。每个 skill 包含三部分：触发条件（什么场景下用）、执行步骤（具体怎么做）、验收标准（做完什么样算对）。智能体在接到任务时，先匹配 skill，再按步骤执行。这样一来，你的经验就固化下来了，不用每次重复。

我打个生活化的比方：提示词像你每次做饭都凭感觉放盐，技能像你写了一张菜谱贴在厨房墙上。前者依赖状态，后者依赖流程。状态会波动，流程可复用。

2.2 为什么选 Claude Code 和 Codex CLI 作为执行层

热搜词里反复出现 Claude Code 和 Codex CLI，不是偶然。这两个工具是目前命令行智能体里工具调用能力比较成熟的两类代表。Claude Code 的优势在于它对终端命令的直接执行、对文件系统的读写、以及对 VS Code 的深度集成；Codex CLI 的优势在于命令语义清晰，/compact、/model、/resume这些指令让会话管理很顺手。

superpowers 作为技能框架，本身不绑定具体执行器。你可以把它理解成一套“接口规范”，Claude Code 能接，Codex CLI 也能接。选哪个取决于你的场景：如果你主要在 VS Code 里写代码，希望智能体能直接改文件、跑测试，Claude Code 的 VS Code 插件体验更顺；如果你习惯纯终端操作，喜欢用/resume恢复会话、用/compact压缩上下文，Codex CLI 更对味。

这里有个关键设计取舍：技能文件用 Markdown 而不是 JSON 或 YAML。原因是 Markdown 对模型友好，模型读 Markdown 的指令遵循率明显高于读结构化配置。而且 Markdown 方便人写、方便版本控制、方便 diff。你把它放进 Git 仓库，团队每个人都能改，改完提交，下次智能体加载的就是最新版。

2.3 技能加载机制背后的上下文经济学

很多人没意识到，智能体的上下文窗口是稀缺资源。你把所有技能一次性塞进去，模型反而会“注意力涣散”。superpowers 的做法是按需加载：智能体先读一个索引文件（通常叫SKILLS.md或skills/index.md），里面列出所有技能的名称和一句话描述；当任务匹配到某个技能时，再读取该技能的完整文件。

这个机制的好处，我用一个数字说明。假设你有 20 个技能，每个平均 800 字，全量加载就是 16000 字，差不多占掉 Claude 上下文窗口的一大块。按需加载的话，索引可能只有 500 字，单个技能 800 字，总共 1300 字，省了 90% 以上。省下来的上下文，留给实际代码和任务描述，模型的表现会明显更稳。

注意：索引文件的描述要写得“可匹配”。比如“用于生成单元测试”就比“测试相关”好，因为智能体是靠语义匹配来选技能的，描述越具体，选错概率越低。

3. 核心细节解析与实操要点：技能文件怎么写才有效

3.1 一个合格 skill 文件的四段式结构

我踩过几次坑之后，总结出一个 skill 文件最稳的结构是四段：适用场景、前置条件、执行步骤、验收清单。少一段都会出问题。

适用场景写清楚“什么时候用这个技能”。比如“当用户要求为新函数补充测试时”就比“写测试”精确。前置条件写“执行前需要确认什么”，比如“确认项目已安装 Jest 且 package.json 里有 test 脚本”。执行步骤是核心，要写成有序列表，每步一个动作，动作要具体到命令级别。验收清单写“做完后检查哪几项”，比如“测试文件命名符合*.test.ts规范”“至少覆盖正常路径和边界路径”。

我见过有人把 skill 写成一大段散文，模型读完不知道从哪下手。也见过有人写成纯命令列表，缺少判断逻辑，遇到异常就卡住。四段式的好处是，模型先判断场景对不对，再检查条件满不满足，然后按步骤走，最后自检。这跟人类工程师做事的方式是一致的。

3.2 触发词设计：让智能体“该出手时才出手”

技能框架最容易翻车的地方，是误触发。你写了一个“重构函数”的技能，结果模型在你只是想“看看这个函数干嘛的”时候也去重构，那就麻烦了。解决办法是在技能文件开头加一段触发词与反触发词。

触发词是“出现这些词才考虑用”，比如“重构”“提取方法”“消除重复”。反触发词是“出现这些词就别用”，比如“解释”“阅读”“只是看看”。这看起来简单，但实际效果差别很大。我实测下来，加了反触发词之后，误触发率能降一半以上。

另外，触发词要覆盖同义表达。用户可能说“重构”，也可能说“整理一下这个函数”，还可能说“这段代码太乱了帮我理理”。你不可能穷举，但可以把最常见的三五种写进去。剩下的靠模型语义理解兜底。

3.3 技能之间的依赖与组合

真实项目里，任务很少是单一的。比如“给这个模块加一个新功能”，可能涉及“读代码”“写实现”“写测试”“更新文档”四个技能。superpowers 的处理方式是允许技能声明依赖：在技能文件里写一行depends_on: [read-code, write-test]，智能体加载主技能时，会把依赖技能一起加载。

但这里有个坑：依赖不能成环。A 依赖 B，B 又依赖 A，模型会陷入循环加载。我的做法是画一张依赖图，确保是 DAG（有向无环图）。如果两个技能确实互相需要，就抽一个公共技能出来，让两者都依赖它。

组合技能的时候，还要注意执行顺序。通常的顺序是：先读后写，先实现后测试，先测试后文档。这个顺序不是死的，但偏离太多容易出问题。比如你先写文档再写实现，文档大概率跟实现对不上。

3.4 版本管理与团队协作

技能文件放 Git 里管理，这点前面提过。但具体怎么管，有几个细节值得说。第一，每个技能一个文件，不要把所有技能塞一个巨型文件，否则 diff 的时候看不清改了啥。第二，技能文件加 frontmatter，写上作者、最后更新时间、适用版本范围。第三，改动技能要写 commit message，说明为什么改，比如“修复 write-test 技能在 Vitest 项目下误用 Jest 命令的问题”。

团队协作时，建议指定一个“技能维护者”角色，负责审核技能改动。因为技能是给智能体看的，写得太随意会导致模型行为不稳定。审核要点就三条：触发条件是否清晰、步骤是否可执行、验收标准是否可检验。

4. 实操过程与核心环节实现：从零搭一套可用的技能框架

4.1 环境准备：Claude Code 与 Codex CLI 的安装配置

先说 Claude Code 的安装。macOS 和 Ubuntu 下，官方推荐的方式是通过包管理器安装，装完之后在终端输入claude就能进入交互界面。Windows 用户注意，热搜里出现过“claude code 由于与64位版本的windows不兼容”这类问题，通常是环境变量或终端模拟器的问题，建议用 WSL2 或者官方推荐的终端环境。VS Code 用户可以直接装 Claude Code 的 VS Code 插件，装完后在设置里配置好路径，就能在编辑器里直接调用。

Codex CLI 的安装类似，装完后常用命令有这么几个：/compact用来压缩当前会话上下文，防止太长；/model用来切换模型；/resume用来恢复之前的会话。删除 Codex CLI 的话，用对应的包管理器卸载命令即可，配置文件一般在用户目录下的隐藏文件夹里，卸载后手动清理一下更干净。

提示：如果你在配置过程中遇到“your organization has disabled claude subscription access”这类提示，说明你的账号权限或订阅状态有问题，这属于账号层面的事，本文不展开。你需要做的是确认自己的账号状态，而不是找绕过办法。

关于用本地模型，热搜里有人问“claude code 调用 lmstudio 的本地模型”。这个思路是可行的，核心是把本地模型的 API 端点配置成兼容格式，然后在 Claude Code 的配置里指向本地地址。但要注意，本地模型的能力和云端模型有差距，复杂任务上表现会打折扣，适合做简单补全和格式化。

4.2 目录结构设计：让技能“找得到、读得快”

我推荐的目录结构是这样的：

project-root/ skills/ index.md read-code.md write-test.md refactor.md commit-message.md .claude/ config.json

skills/放所有技能文件，index.md是索引，.claude/放 Claude Code 的配置。Codex CLI 的话，配置目录名不同，但结构类似。

索引文件index.md的写法很关键。我一般写成表格：

这样模型一眼就能扫完，匹配效率高。表格比列表好，因为列对齐后信息密度更高。

4.3 编写第一个技能：以“生成提交信息”为例

我拿“生成提交信息”这个技能做示范，因为它足够简单，又能体现完整结构。

适用场景：当用户完成一次代码改动，需要生成符合 Conventional Commits 规范的提交信息时。

前置条件：确认当前目录是 Git 仓库，且git status有未提交改动。

执行步骤：

1. 运行git diff --staged查看暂存区改动，如果没有暂存内容，运行git diff查看工作区改动。
2. 分析改动涉及的文件类型和改动性质，判断是 feat、fix、refactor、docs、test 中的哪一类。
3. 提取改动的核心意图，用一句话概括，不超过 50 个字符。
4. 如果改动涉及多个不相关的内容，提示用户拆分提交。
5. 按<type>(<scope>): <subject>格式生成提交信息。

验收清单：

• type 是 feat/fix/refactor/docs/test/chore 之一。
• subject 用祈使句，首字母小写，结尾不加句号。
• 如果改动超过 3 个文件且涉及不同模块，已提示拆分。

这个技能写完之后，我实测了十几次，生成的提交信息基本不用改。关键就在于验收清单把格式约束住了，模型不会自由发挥。

4.4 把技能接进日常工作流

技能写好了，怎么让它真正用起来？我的做法是在项目根目录放一个CLAUDE.md或AGENTS.md，里面写一句话：“执行任务前先读取 skills/index.md，匹配到技能后按技能文件执行。”这样每次启动 Claude Code 或 Codex CLI，它都会先加载索引。

然后就是在实际任务中观察。第一次用可能会发现技能没被触发，或者触发了但步骤没走完。这时候不要急着改技能，先看模型的执行日志，判断是触发词没匹配上，还是步骤描述有歧义。我一般会迭代两三轮，技能就稳定了。

还有一个技巧：给技能加“示例”段落。在技能文件末尾附一个输入输出示例，模型看到示例后，执行准确率会明显提升。比如“生成提交信息”技能里附一个feat(auth): add login validation的例子，模型就知道格式长什么样。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 技能不触发或误触发怎么排查

技能不触发，九成是触发词写得太窄。比如你写“重构”，用户说“优化一下结构”，模型就匹配不上。解决办法是把触发词扩展成一组同义表达，并且在索引文件的描述里也带上这些词。

误触发的话，先看反触发词够不够。我遇到过一次，用户说“帮我看看这个函数”，结果模型触发了重构技能。后来在重构技能里加了反触发词“看看”“解释”“阅读”，问题就解决了。

还有一个隐蔽原因：索引文件太长。如果索引超过 2000 字，模型扫的时候会漏。解决办法是索引只保留技能名和一句话描述，详细内容放各自文件里。

5.2 上下文被技能占满导致任务失败

这是按需加载没做好的典型症状。表现是模型执行到一半开始“胡言乱语”，或者忘记前面的步骤。排查方法是看当前会话的上下文占用，如果技能内容占了超过一半，就要优化。

优化手段有三个：一是拆分大技能，把 800 字的技能拆成两个 400 字的；二是把技能里的示例移到单独文件，需要时再加载；三是用/compact（Codex CLI）或对应的压缩命令清理历史对话。

5.3 技能执行结果不稳定的三种典型情况

第一种，步骤描述有歧义。比如“检查代码质量”这种描述，模型不知道检查什么。改成“检查是否有未使用的变量、是否有超过 50 行的函数、是否有重复代码块”就具体了。

第二种，验收标准不可检验。比如“代码要优雅”，这没法检验。改成“函数不超过 30 行、命名符合 camelCase、无 console.log 残留”就可检验了。

第三种，技能之间冲突。两个技能对同一件事给了不同指令，模型会随机选一个。解决办法是定期审查技能库，发现冲突就合并或明确优先级。

5.4 常见问题速查表

5.5 我踩过的三个印象最深的坑

第一个坑，技能文件用了太多专业缩写。我写了个技能叫“DRY 重构”，结果模型不知道 DRY 是 Don't Repeat Yourself，执行时完全跑偏。后来改成“消除重复代码重构”，就正常了。教训是：技能是给模型看的，不是给人类专家看的，能用大白话就别用缩写。

第二个坑，技能里写了“根据情况选择”。这种描述对模型来说等于没写，因为它不知道“情况”是什么。后来我改成“如果函数超过 50 行，提取子函数；如果参数超过 4 个，封装成配置对象”，模型就能执行了。教训是：把判断条件写死，别让模型自己悟。

第三个坑，技能更新后没通知团队。有次我改了一个测试技能的框架配置，从 Jest 换成 Vitest，但没告诉同事。结果同事用旧技能跑测试，一直报错。后来我们约定，技能改动必须在群里说一声，并且 commit message 写清楚影响范围。教训是：技能是团队资产，改动要同步。

6. 技能框架的扩展玩法与个人经验

6.1 把技能框架接到其他工具链上

superpowers 这套思路不局限于 Claude Code 和 Codex CLI。我试过把它接到其他支持工具调用的智能体上，核心改动只有一处：把技能加载的触发指令换成对应工具的配置方式。比如有的工具用system prompt注入，有的用配置文件，有的用插件机制。只要能让智能体在任务开始前读到索引文件，这套框架就能跑。

热搜里有人问“飞书如何连接 claude code”，这属于把智能体接进协作工具的场景。思路是类似的：在飞书机器人里配置一个命令入口，收到指令后转发给 Claude Code 执行，再把结果返回。技能框架在这里的作用是保证执行的一致性，不管从哪个入口进来，行为都一样。

6.2 技能库的长期维护策略

技能库用久了会膨胀，需要定期清理。我的做法是每季度做一次“技能审计”：统计每个技能过去三个月的触发次数，触发次数为零的考虑删除或合并；触发次数高但经常出错的优先优化；触发次数高且稳定的保持不动。

另外，技能文件要加“最后验证时间”。因为工具链会更新，模型会升级，半年前好用的技能现在可能不适用了。我一般每两个月把核心技能跑一遍，确认还能用。

6.3 关于“要不要用第三方 API”的取舍

热搜里有人问“第三方 api 使用技巧”，也有人问“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”。我的看法是：技能框架本身不依赖特定模型，但模型能力会影响技能执行效果。复杂技能（比如多步重构）建议用能力强的模型，简单技能（比如格式化提交信息）用便宜模型就行。

切换模型的时候，要注意技能的兼容性。不同模型对指令的遵循程度不同，同一个技能在 A 模型上跑得好，在 B 模型上可能跑偏。解决办法是在技能文件里标注“适用模型范围”，切换时先小范围测试。

6.4 我个人的使用体会

用这套框架大半年，最大的感受是：它把 AI 编程从“碰运气”变成了“可管理”。以前用 Claude Code，每次都要祈祷它今天状态好；现在有了技能库，行为稳定多了，团队新人上手也快，因为技能文件本身就是最好的操作手册。

最后分享一个小技巧：给技能文件加一个“失败案例”段落。把你踩过的坑写进去，比如“不要在这个技能里用git add .，会误加无关文件”。模型读到失败案例后，会主动避开这些坑。这个技巧我用了之后，技能的一次通过率又提升了一截。