Superpowers 技能框架：终端智能体开发实战指南

1. 从“superpowers”说起：一个被低估的智能体技能框架

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的智能体工具，大概率已经在某些技术社区里刷到过它。简单来说，superpowers 是一套面向智能体（agent）的技能框架与软件开发方法论，它要解决的问题非常具体：当你在终端里让 AI 帮你写代码、跑命令、改项目时，怎么让它的行为可控、可复用、可组合，而不是每次都靠一段又长又随意的提示词去“碰运气”。

我最初接触它，是因为在用 Claude Code 做一个小型重构任务时，发现每次都要重复描述项目结构、编码规范、测试命令，效率极低。后来顺着 agentic skills framework 这条线摸到了 superpowers 的思路——把“技能”从提示词里抽出来，变成独立、可版本管理、可被多个智能体调用的模块。这个转变听起来简单，但实际用下来，它直接改变了我和终端智能体的协作方式。

这篇文章适合三类人：一是已经在用 Claude Code 或 Codex CLI，但总觉得“差点意思”的开发者；二是想给自己的项目引入一套可维护的 AI 协作流程的技术负责人；三是刚听说这些工具、还在纠结要不要装、怎么装的新手。我会从设计思路讲到实操细节，包括安装配置、技能编写、常见坑，以及我在 Ubuntu 和 macOS 上踩过的那些雷。你不需要是 AI 专家，只要会用终端、写过一点代码，就能跟着复现。

2. 为什么需要 superpowers：终端智能体的真实痛点

2.1 提示词堆砌的尽头是混乱

刚开始用 Claude Code 的时候，我和大多数人一样，把需求一股脑塞进对话里：“帮我改一下这个函数，注意用 TypeScript 严格模式，测试用 vitest，别动 public 目录……”第一次还行，第二次换个任务，又得重新说一遍。更麻烦的是，当项目里有多个模块、多个规范时，提示词会膨胀到几百字，模型还经常“选择性遗忘”其中几条。

这就是典型的提示词堆砌问题。它有三个致命伤：不可复用、不可测试、不可组合。你没法像管理代码一样管理提示词，也没法保证今天有效的提示词明天还管用。superpowers 的核心洞察就在这里——把技能（skill）当作一等公民，每个技能是一个独立单元，有明确的输入、输出、触发条件和执行逻辑，智能体在需要时加载对应技能，而不是把所有东西都塞进上下文。

2.2 技能框架 vs 传统提示词工程

传统提示词工程更像是“一次性脚本”，而 agentic skills framework 更像是“函数库”。我打个比方：提示词工程是你每次做饭都从头切菜配料，技能框架是你提前把葱姜蒜切好、调料配好，做饭时直接取用。区别在于，前者依赖你的记忆和临场发挥，后者依赖结构化的资产。

具体到 superpowers 的设计，它通常包含几个关键要素：技能描述文件（说明这个技能干什么、什么时候用）、执行指令（具体的步骤或代码）、依赖声明（需要哪些工具或环境）、以及验证方式（怎么知道技能执行成功了）。这套结构让智能体在遇到类似任务时，能自动匹配技能，而不是每次重新推理。

2.3 它到底解决了哪些具体问题

我在实际项目里总结了几类 superpowers 最能发挥价值的场景。第一类是重复性开发任务，比如“新增一个 API 端点并补测试”，这种任务步骤固定，写成技能后一句话就能触发。第二类是规范约束，比如“所有提交必须通过 lint 和类型检查”，技能里内置检查命令，智能体不会跳过。第三类是跨工具协作，比如在 Claude Code 里调用 Codex CLI 做代码审查，技能负责编排两个工具的输入输出。

还有一类容易被忽略的场景：新人上手。团队里新来的同学不熟悉项目规范，直接让智能体按技能执行，产出的代码风格和流程就是统一的。这比写一堆文档管用得多，因为文档没人看，但智能体会强制执行。

3. 核心概念拆解：技能、智能体与编排

3.1 什么是“技能”，和普通函数有什么区别

在 superpowers 的语境里，技能不是代码函数，而是一段结构化的行为描述。它可以包含自然语言指令、shell 命令、代码片段、甚至对其他技能的引用。和普通函数最大的区别在于，技能是给智能体“读”的，不是给编译器“执行”的。智能体会根据当前任务和技能描述，决定是否加载、如何执行。

我通常把技能分成三类：原子技能（单一动作，如“运行测试”）、复合技能（多个原子技能的组合，如“提交前检查”）、元技能（管理其他技能，如“根据文件类型选择 lint 工具”）。这种分层让技能库既灵活又可控，不会因为一个技能太复杂而难以维护。

3.2 智能体如何发现和调用技能

智能体发现技能的机制，通常依赖一个技能索引文件。这个文件列出所有可用技能的名称、描述和触发关键词。当你在终端里输入需求时，智能体会先扫描索引，匹配相关技能，然后加载完整技能内容到上下文。这个过程有点像 IDE 的代码补全，只不过补全的是“行为”而不是“符号”。

这里有个关键细节：技能描述的写法直接影响匹配准确率。我试过把技能描述写得太泛（比如“处理代码”），结果智能体经常误触发；后来改成具体场景（比如“当用户要求新增 React 组件时使用”），匹配就准多了。所以写技能描述时，要像写 API 文档一样，明确“什么时候用”和“什么时候不用”。

3.3 编排层：让多个技能协同工作

单个技能能解决的问题有限，真正强大的是编排。比如一个“发布新版本”的任务，可能涉及：运行测试、更新版本号、生成 changelog、打 tag、推送。这些步骤可以拆成五个技能，再由一个编排技能按顺序调用。编排层负责处理依赖关系、错误回滚、条件分支。

我在编排上踩过的最大坑是错误处理。早期写的编排技能没有考虑某一步失败的情况，结果测试没通过还继续打 tag，差点把坏版本发出去。后来学乖了，每个关键步骤后都加检查点，失败就中断并输出日志。这个经验后来成了我写所有编排技能的标准模板。

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

4.1 Claude Code 安装：macOS、Ubuntu 与 VS Code 接入

Claude Code 的安装方式取决于你的系统。在 macOS 上，最省事的是用官方提供的安装脚本，一行命令搞定。但要注意，官方文档里提到的地区限制确实存在，如果你在安装时看到“might not be available in your country”的提示，说明当前网络环境不在支持列表内。这种情况下，可以先检查官方文档链接确认支持范围，再决定后续方案。

Ubuntu 上的安装稍微麻烦一点，因为涉及 Node 环境。我的建议是先用 nvm 管理 Node 版本，避免系统自带 Node 版本过旧导致兼容问题。安装完 Claude Code 后，第一次运行会引导你登录或配置 API。这里有个选择：注册账号和不注册的区别主要在于配额和功能权限，注册后能用官方模型和在线升级，不注册则通常需要自己接第三方 API。

VS Code 接入方面，Claude Code 提供了官方插件。安装插件后，需要在设置里配置可执行文件路径和 API 信息。我实测下来，插件版的优势是能直接在编辑器里看到智能体的操作，不用来回切终端。但如果你习惯纯终端工作流，命令行版更轻快。

4.2 Codex CLI 安装：Node 慢的解决方案

Codex CLI 的安装依赖 Node，国内用户最常遇到的问题是npm 安装速度极慢甚至超时。我试过几种方案：换 registry、用 pnpm、提前下载 tarball。最稳的是换 registry 配合代理缓存，但这里不展开网络细节，只说操作层面——你可以先配置 npm 的 registry 为国内镜像，再执行安装。

安装完成后，Codex CLI 的命令体系需要熟悉一下。常用的有/compact（压缩上下文）、/model（切换模型）、/resume（恢复会话）。这些命令在长任务里特别有用，比如上下文快满的时候用/compact清理，能避免智能体“失忆”。删除 Codex CLI 的指令也很简单，npm 卸载加清理配置目录即可，但记得先备份你的技能库。

4.3 第三方 API 接入与模型切换

很多人关心能不能用第三方 API 接入 DeepSeek、Qwen、GLM 等模型。答案是可以，但需要工具辅助。社区里有类似 cc switch 这样的工具，专门用来切换 Claude Code 的后端模型。配置逻辑通常是：在工具里填入第三方 API 的 endpoint 和 key，然后让 Claude Code 指向本地代理。

这里有个实操心得：不同模型对技能格式的兼容性不一样。我试过用某个国产模型跑同一套技能，发现它对结构化指令的遵循度不如官方模型，经常跳过步骤。所以如果你要接第三方模型，建议先跑几个简单技能测试遵循度，再决定是否用于关键任务。另外，第三方 API 的上下文长度和计费方式也要提前确认，避免长任务跑到一半被截断。

5. 实操：从零搭建一个 superpowers 技能库

5.1 目录结构与技能文件格式

我建议的技能库目录结构是这样的：根目录下放一个skills/文件夹，里面每个技能一个子目录，子目录里至少有一个SKILL.md描述文件。如果技能包含脚本，再放一个scripts/文件夹。根目录还需要一个index.json或index.md作为技能索引，列出所有技能的名称、描述和路径。

SKILL.md的格式我通常包含这几块：名称、触发条件、执行步骤、验证方式、注意事项。触发条件要写得具体，比如“当用户要求新增数据库迁移文件时”。执行步骤用有序列表，每步尽量是可直接执行的命令或明确的操作。验证方式写清楚怎么判断成功，比如“测试全部通过且无 lint 错误”。

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

拿一个实际例子来说。我要写一个“代码审查”技能，触发条件是“用户要求审查当前分支的改动”。执行步骤包括：获取 diff、检查命名规范、检查测试覆盖、输出审查报告。验证方式是“报告生成且包含至少一条改进建议”。

写的时候要注意，步骤不能太抽象。比如“检查命名规范”这种描述，智能体可能不知道怎么检查。我会写成“运行npx eslint --rule 'camelcase: error'并收集输出”。这样智能体就知道具体执行什么命令，而不是自由发挥。另外，技能里可以引用其他技能，比如“调用测试技能运行单元测试”，这样能复用已有逻辑。

5.3 技能编排：把多个技能串成工作流

编排技能的写法稍微不同，它不直接执行命令，而是调用其他技能并处理结果。我通常用一个 YAML 或 JSON 结构来描述编排流程，包含步骤列表、每步调用的技能名、失败处理策略。比如“发布流程”编排：第一步调用测试技能，失败则终止；第二步调用版本更新技能；第三步调用 changelog 技能；第四步调用打 tag 技能。

编排的难点在于状态传递。上一步的输出怎么传给下一步？我的做法是在编排文件里定义变量，每步执行后把关键结果写入变量，下一步读取。比如测试技能输出“通过/失败”，编排层根据这个值决定是否继续。这个机制不复杂，但能大幅提升工作流的可靠性。

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

6.1 安装与配置类问题速查

这张表是我在实际使用中整理出来的，覆盖了八成以上的常见问题。遇到新问题时，我的排查顺序是：先确认工具本身能跑（比如手动执行命令），再确认技能描述是否被正确加载，最后看模型是否遵循了指令。

6.2 技能执行失败的典型原因

技能执行失败，最常见的原因不是工具坏了，而是技能描述有歧义。比如我写过一个“格式化代码”技能，描述里只说“运行格式化工具”，结果智能体有时跑 prettier，有时跑 eslint --fix，行为不一致。后来改成明确指定“运行npx prettier --write .”，就稳定了。

另一个原因是环境依赖缺失。技能里用了某个命令，但当前环境没装。这种情况智能体会报错，但错误信息可能不直观。我的做法是在技能开头加一个“前置检查”步骤，确认依赖存在再继续。这样失败时能快速定位，而不是在一堆输出里找线索。

6.3 上下文管理与性能优化

长任务里，上下文管理是绕不开的。Claude Code 的/compact命令能压缩上下文，但压缩后可能丢失细节。我的经验是：在关键步骤前手动保存状态，比如把当前进度写入一个临时文件，压缩后让智能体重新读取。这样即使上下文被清理，任务也能继续。

性能方面，技能库不宜过大。我试过把几十个技能全加载到索引里，结果智能体匹配变慢，还经常选错。后来按项目类型拆分技能库，每个项目只加载相关技能，速度和准确率都上来了。这个思路和微服务拆分有点像，按需加载，避免全局膨胀。

7. 我的实操心得与后续扩展方向

用 superpowers 这套思路折腾了几个月，最大的体会是：技能库的质量比数量重要得多。我一开始贪多，写了二十多个技能，结果一半以上从没用过，还拖慢了匹配。后来砍到八个核心技能，覆盖日常八成任务，反而效率最高。所以如果你刚开始，建议先写三个：一个跑测试、一个做代码审查、一个处理提交。跑顺了再扩展。

另一个心得是技能要跟着项目演进。项目规范变了，技能不更新，智能体就会按旧规范执行，产出不一致的代码。我现在把技能库纳入版本管理，每次项目规范调整，同步更新技能，并在提交信息里注明。这样团队里其他人拉取后，智能体的行为也跟着更新。

后续扩展方向，我比较看好技能的市场化共享。现在已经有人把通用技能打包发布，比如 React 项目技能包、Python 数据科学技能包。如果这个生态成熟，以后搭项目可能就像装依赖一样，直接引入一套技能库，智能体立刻具备该领域的规范行为。当然，这需要技能格式标准化和安全审查机制，目前还在早期阶段。

最后分享一个小技巧：给技能写测试。听起来有点怪，但确实有用。我会写一个简单的脚本，模拟用户输入，检查智能体是否触发了预期技能、是否执行了正确命令。这能提前发现描述歧义和依赖问题，比等到实际任务里翻车强。这个习惯是从传统软件开发里带过来的，用在智能体技能上同样成立。