★ FEATURED ARTICLE 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 安装与配置类问题速查问题现象可能原因排查方向Claude Code 提示地区不支持网络环境不在支持列表查官方文档确认支持范围Codex CLI 安装卡住npm registry 慢换国内镜像或提前下载VS Code 插件找不到命令路径未配置检查插件设置里的可执行文件路径第三方 API 调用失败endpoint 或 key 错误先用 curl 测试 API 连通性技能不触发描述太泛或关键词不匹配细化触发条件加具体场景词这张表是我在实际使用中整理出来的覆盖了八成以上的常见问题。遇到新问题时我的排查顺序是先确认工具本身能跑比如手动执行命令再确认技能描述是否被正确加载最后看模型是否遵循了指令。6.2 技能执行失败的典型原因技能执行失败最常见的原因不是工具坏了而是技能描述有歧义。比如我写过一个“格式化代码”技能描述里只说“运行格式化工具”结果智能体有时跑 prettier有时跑 eslint --fix行为不一致。后来改成明确指定“运行npx prettier --write .”就稳定了。另一个原因是环境依赖缺失。技能里用了某个命令但当前环境没装。这种情况智能体会报错但错误信息可能不直观。我的做法是在技能开头加一个“前置检查”步骤确认依赖存在再继续。这样失败时能快速定位而不是在一堆输出里找线索。6.3 上下文管理与性能优化长任务里上下文管理是绕不开的。Claude Code 的/compact命令能压缩上下文但压缩后可能丢失细节。我的经验是在关键步骤前手动保存状态比如把当前进度写入一个临时文件压缩后让智能体重新读取。这样即使上下文被清理任务也能继续。性能方面技能库不宜过大。我试过把几十个技能全加载到索引里结果智能体匹配变慢还经常选错。后来按项目类型拆分技能库每个项目只加载相关技能速度和准确率都上来了。这个思路和微服务拆分有点像按需加载避免全局膨胀。7. 我的实操心得与后续扩展方向用 superpowers 这套思路折腾了几个月最大的体会是技能库的质量比数量重要得多。我一开始贪多写了二十多个技能结果一半以上从没用过还拖慢了匹配。后来砍到八个核心技能覆盖日常八成任务反而效率最高。所以如果你刚开始建议先写三个一个跑测试、一个做代码审查、一个处理提交。跑顺了再扩展。另一个心得是技能要跟着项目演进。项目规范变了技能不更新智能体就会按旧规范执行产出不一致的代码。我现在把技能库纳入版本管理每次项目规范调整同步更新技能并在提交信息里注明。这样团队里其他人拉取后智能体的行为也跟着更新。后续扩展方向我比较看好技能的市场化共享。现在已经有人把通用技能打包发布比如 React 项目技能包、Python 数据科学技能包。如果这个生态成熟以后搭项目可能就像装依赖一样直接引入一套技能库智能体立刻具备该领域的规范行为。当然这需要技能格式标准化和安全审查机制目前还在早期阶段。最后分享一个小技巧给技能写测试。听起来有点怪但确实有用。我会写一个简单的脚本模拟用户输入检查智能体是否触发了预期技能、是否执行了正确命令。这能提前发现描述歧义和依赖问题比等到实际任务里翻车强。这个习惯是从传统软件开发里带过来的用在智能体技能上同样成立。
阅读完成 · 觉得有帮助？
