1. 拆解 superpowers它到底想解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子尤其是在 Claude Code 和 Codex CLI 的社区里泡过一段时间就会发现这个词出现的频率越来越高。它指的其实是一套agentic skills framework翻译过来就是“智能体技能框架”。说白了它想做的事情是给 AI 编程助手装上一套可复用、可组合、可扩展的“技能包”让 AI 不再只是被动地回答问题而是能主动调用工具、执行任务、完成从需求到代码落地的完整闭环。我最初接触这个概念是在一个深夜调试 Claude Code 的时候。当时我正被一个重复性的代码重构任务折磨——需要在十几个文件里统一修改某个接口的调用方式手动改容易漏写脚本又觉得不值当。后来在社区里看到有人提到 superpowers 这个框架说它可以定义一套“技能”让 AI 按照预设的流程去执行这类批量操作。我抱着试试看的心态研究了一下发现它的设计思路确实有点东西。核心问题在于现在的 AI 编程工具虽然强大但每次对话都是“一次性”的。你告诉它做什么它就做什么下次遇到类似任务还得重新描述一遍。这就好比你招了一个很聪明的实习生但他没有“肌肉记忆”每次都得从头教。superpowers 要解决的就是这个“肌肉记忆”的问题——通过定义标准化的技能模块让 AI 能够积累和复用解决问题的能力。这套框架适合谁来用我的判断是三类人第一类是日常使用 Claude Code 或 Codex CLI 进行开发的工程师想提升重复性任务的效率第二类是对 AI 智能体agent架构感兴趣的技术爱好者想理解技能框架的设计哲学第三类是团队技术负责人在考虑如何把 AI 编程工具规范化地引入团队工作流。不管你属于哪一类理解 superpowers 的设计思路和实操方法都能帮你更好地驾驭手头的 AI 工具。2. 核心设计思路为什么是“技能”而不是“提示词”2.1 从提示词工程到技能工程的演进逻辑过去两年大家聊 AI 编程工具绕不开的一个词是“提示词工程”Prompt Engineering。你花大量时间打磨一段提示词让 AI 输出更符合预期的结果。但提示词有个天然缺陷它是扁平的、一次性的、难以组合的。你写了一段很棒的提示词用来生成单元测试另一段用来做代码审查但它们之间没法自动串联起来。superpowers 的思路是把“提示词”升级成“技能”。一个技能不仅仅是一段文字描述它包含了几个关键要素触发条件什么时候该用这个技能、执行步骤具体怎么做、依赖工具需要调用哪些外部能力、输出规范结果应该长什么样。这就像从“写便签”升级到了“写函数”——便签只能贴在那儿提醒你函数却可以被调用、被组合、被复用。我个人的理解是这个演进方向是必然的。因为 AI 编程工具的能力边界在快速扩展从最早的代码补全到现在的多文件编辑、终端命令执行、甚至自主规划任务。能力越强就越需要一套结构化的方式来管理这些能力。否则就像给一个大力士一堆没有标签的工具他力气再大也不知道该用哪个。2.2 技能框架的四个核心抽象拆解 superpowers 的设计我认为它建立在四个核心抽象之上。理解这四个抽象基本就理解了整个框架的骨架。第一个是 Skill技能。这是最基本的单元一个技能对应一类任务。比如“生成 API 文档”“重构函数签名”“批量替换导入路径”都可以是一个技能。每个技能有明确的输入和输出定义以及执行所需的上下文。第二个是 Trigger触发器。它决定了技能在什么条件下被激活。触发器可以是关键词匹配、文件类型判断、甚至是 AI 自主决策。比如你定义了一个“Python 代码格式化”技能触发器可以设置为“当用户提到格式化或文件后缀为 .py 时激活”。第三个是 Toolchain工具链。技能执行过程中需要调用的外部工具集合。在 Claude Code 的语境下这可能包括文件读写、终端命令执行、代码搜索等。Codex CLI 也有类似的工具调用机制。superpowers 的价值在于把这些工具调用标准化让技能定义不需要关心底层是哪个工具在干活。第四个是 Context上下文。这是最容易被忽视但最关键的部分。技能执行时需要知道当前项目的结构、代码风格、依赖关系等信息。superpowers 通过上下文注入机制让技能能够“感知”到当前的工作环境而不是盲目执行。2.3 与 Claude Code、Codex CLI 的协作关系这里需要澄清一个常见的误解superpowers 不是一个独立的工具它更像是一层“中间件”架在 AI 编程助手和具体任务之间。你可以把它理解成给 Claude Code 或 Codex CLI 装了一个“技能插件系统”。Claude Code 本身提供了强大的基础能力——读写文件、执行终端命令、理解代码上下文。Codex CLI 也有类似的能力集。但它们默认的工作模式是“你问我答”缺少一个结构化的技能管理层。superpowers 补的就是这一层。它让你可以定义技能、管理技能、组合技能然后通过 Claude Code 或 Codex CLI 来执行。我实测下来的感受是这种分层设计的好处在于解耦。你的技能定义不依赖于具体的 AI 工具今天用 Claude Code 执行明天换成 Codex CLI 也能跑。这对于团队协作特别有价值——不会因为某个人换了工具整套工作流就废了。3. 环境准备从零搭建可运行的技能框架3.1 基础环境的选择与配置在动手之前得先把基础环境搭好。根据我的经验推荐的环境组合是 Ubuntu 22.04 或 macOS配合 Node.js 18 以上的版本。Windows 用户如果遇到兼容性问题建议使用 WSL2这个在社区里已经是共识了。为什么强调 Ubuntu 和 macOS因为 Claude Code 和 Codex CLI 在这两个平台上的支持最完善。特别是涉及到终端命令执行和文件系统操作时Linux 和 macOS 的行为更可预测。我在 Windows 原生环境下试过偶尔会遇到路径分隔符和权限相关的小问题虽然能解决但会浪费不少时间。Node.js 的版本选择也有讲究。18 版本是当前大多数 AI 编程工具的最低要求但我建议直接上 20 LTS。原因很简单新版本对 ES Module 的支持更完整而很多技能框架的配置文件用的是 ESM 格式。用旧版本可能会遇到require和import混用的报错。安装 Node.js 我习惯用 nvm这样可以在不同项目间切换版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20装完之后用node -v确认一下版本看到 v20.x.x 就对了。3.2 Claude Code 的安装与初始化Claude Code 的安装方式取决于你的使用场景。如果你只是想快速体验可以用 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在项目目录下运行claude命令它会引导你完成初始化。这里有个细节需要注意初始化过程中会要求你登录账号。如果你所在的环境无法直接登录社区里也有通过第三方 API 接入的方案比如使用 cc switch 这类工具来切换不同的模型后端。具体选择哪种方式取决于你的实际网络环境和使用需求。初始化完成后Claude Code 会在项目根目录生成一个配置文件。这个文件很关键它定义了 Claude Code 的行为边界——哪些目录可以访问、哪些命令可以执行、上下文窗口多大等等。我建议一开始把权限收窄一些只开放当前项目目录避免误操作影响到其他文件。如果你用的是 VS Code还可以安装 Claude Code 的官方插件。装好之后在 VS Code 的设置里配置一下插件路径就能在编辑器内直接调用 Claude Code 的能力。这个体验比在终端里切换窗口要顺畅得多特别是需要频繁查看代码改动的场景。3.3 Codex CLI 的安装与基础命令Codex CLI 是另一个常用的 AI 编程命令行工具。安装方式同样是 npmnpm install -g openai/codex-cli安装完成后运行codex进入交互模式。Codex CLI 有几个常用命令值得记住/compact用来压缩对话历史节省上下文窗口/model用来切换底层模型/resume用来恢复之前的会话。这些命令在长时间开发过程中特别有用尤其是/compact当你感觉 AI 开始“忘事”的时候压缩一下历史往往能让它重新聚焦。如果需要删除 Codex CLI用npm uninstall -g openai/codex-cli就行。但要注意卸载不会自动清理配置文件手动删一下~/.codex目录更干净。3.4 技能框架的引入与目录结构基础工具装好之后就可以引入 superpowers 技能框架了。根据社区里的常见实践通常是在项目根目录下创建一个skills目录里面按技能名称分子目录存放。每个技能目录包含一个定义文件通常是 YAML 或 JSON 格式和可选的辅助脚本。目录结构大概长这样project-root/ skills/ format-python/ skill.yaml scripts/ format.py generate-docs/ skill.yaml templates/ api-doc.md .claude/ config.json这种结构的优势在于清晰。每个技能是自包含的复制到其他项目也能直接用。我在多个项目之间复用技能时直接拷贝对应的子目录就行不需要改任何配置。4. 技能定义实操从第一个技能开始4.1 技能定义文件的结构解析一个标准的技能定义文件包含几个核心字段。我以一个“Python 代码格式化”技能为例展示完整的定义结构name: format-python description: 对指定 Python 文件执行格式化统一代码风格 trigger: keywords: - 格式化 - format - 代码风格 file_patterns: - *.py inputs: - name: target_files type: file_list description: 需要格式化的文件列表 required: true - name: style_config type: string description: 格式化风格配置默认为 black default: black steps: - action: validate_files description: 检查文件是否存在且为 Python 文件 - action: run_formatter tool: terminal command: black {{target_files}} description: 调用 black 执行格式化 - action: report_result description: 汇总格式化结果并输出 output: format: markdown template: | 格式化完成共处理 {{file_count}} 个文件。 变更文件列表 {{changed_files}}这个定义文件的信息量很大我逐块拆解一下。trigger部分定义了技能何时被激活——当用户输入包含“格式化”等关键词且涉及.py文件时这个技能就会被触发。inputs定义了技能需要的输入参数这里需要用户提供目标文件列表和可选的风格配置。steps是执行步骤每一步可以是一个校验动作、一个工具调用、或者一个结果汇总。output定义了最终输出的格式。4.2 触发条件的设置技巧触发条件的设置是技能框架里最需要打磨的部分。设得太宽技能会被频繁误触发干扰正常工作设得太窄又起不到自动化的效果。我的经验是采用“关键词 文件模式”的双重匹配策略。关键词负责语义层面的判断文件模式负责上下文层面的过滤。比如“格式化”这个词如果单独作为触发条件用户在讨论代码风格时也可能触发。但加上.py文件模式的限制就只有真正涉及 Python 文件操作时才会激活。另一个技巧是设置优先级。当多个技能同时满足触发条件时优先级高的先执行。比如“重构函数签名”和“格式化代码”可能都会被“重构”这个词触发但前者应该优先因为重构完成后通常还需要格式化。优先级用数字表示数字越小优先级越高。注意触发条件不要设置得太复杂。我见过有人写了十几条正则表达式来匹配触发条件结果调试成本极高而且容易漏掉边缘情况。保持简单两到三个条件组合就够了。4.3 工具调用的参数传递与错误处理技能执行过程中调用外部工具时参数传递的准确性直接决定了技能能不能跑通。这里有几个实操要点。首先是变量替换的语法。不同框架的语法略有差异但常见的是{{variable_name}}这种双花括号形式。需要注意的是变量替换发生在命令执行之前所以如果变量值里包含特殊字符比如空格、引号需要提前做转义处理。我在一个批量重命名的技能里就踩过这个坑——文件名里有空格导致命令被截断后来加了引号包裹才解决。其次是错误处理。工具调用失败是常态网络超时、文件不存在、权限不足都可能发生。技能定义里应该包含错误处理逻辑比如失败后重试几次、或者跳过当前文件继续处理下一个。我通常会在技能定义里加一个on_error字段指定失败时的行为steps: - action: run_formatter tool: terminal command: black {{target_files}} on_error: continue max_retries: 2on_error: continue表示出错后继续执行后续步骤max_retries: 2表示最多重试两次。这种配置在处理批量文件时特别实用不会因为一个文件的问题导致整个任务中断。4.4 上下文注入让技能“看懂”项目上下文注入是 superpowers 框架里比较高级的特性。简单说就是让技能在执行时能够获取到项目的相关信息比如目录结构、依赖列表、代码风格配置等。实现方式通常有两种。一种是在技能定义里声明需要哪些上下文框架自动收集后注入context: - project_structure - dependencies - code_style_config另一种是通过预处理脚本动态生成上下文。比如你想让技能知道当前 Git 分支和最近的提交记录可以写一个脚本在技能执行前运行把结果作为上下文传入。我个人的体会是上下文注入用好了能大幅提升技能的智能程度。比如一个“生成单元测试”的技能如果它能读取到项目的测试框架配置是 pytest 还是 unittest、Mock 库的偏好、以及现有测试文件的命名规范生成的测试代码就会更贴合项目实际减少后期调整的工作量。5. 与 Claude Code 和 Codex CLI 的深度集成5.1 在 Claude Code 中调用技能Claude Code 本身没有原生的技能框架概念但可以通过几种方式实现类似效果。最直接的方式是利用 Claude Code 的“自定义命令”功能。你可以在项目配置里定义一些快捷命令每个命令对应一段预设的提示词或脚本调用。比如定义一个/format命令当你在 Claude Code 里输入这个命令时它会自动加载skills/format-python/skill.yaml里的定义然后按照步骤执行。这种方式的优点是集成度高不需要切换工具缺点是灵活性受限于 Claude Code 的命令机制。另一种方式是通过 Claude Code 的 API 接口把技能框架作为一个外部服务来调用。Claude Code 负责理解用户意图和生成代码技能框架负责执行具体的工具调用和流程控制。这种架构更适合复杂的多步骤任务。5.2 在 Codex CLI 中集成技能Codex CLI 的集成思路类似但命令体系有所不同。Codex CLI 支持通过配置文件定义自定义指令你可以把技能定义转换成 Codex CLI 能识别的格式。一个实用的技巧是利用 Codex CLI 的/model命令切换不同能力的模型。比如简单的格式化任务用轻量模型就够了复杂的重构任务切换到更强的模型。技能定义里可以指定推荐的模型类型执行时自动切换。execution: recommended_model: claude-sonnet fallback_model: claude-haiku这种配置在成本敏感的场景下很有价值。不是所有任务都需要最强的模型合理分配能省下不少开销。5.3 跨工具的技能复用策略技能定义和具体 AI 工具解耦之后跨工具复用就变得可行了。我的做法是把技能定义放在一个独立的 Git 仓库里作为团队的“技能库”。每个项目通过子模块或包管理的方式引入需要的技能。这样带来的好处是技能可以版本化管理。当某个技能的逻辑需要调整时改一处所有引用它的项目都能受益。同时新成员加入团队时直接拉取技能库就能获得一套标准化的 AI 辅助工作流不需要从头摸索。提示技能库的维护需要制定规范。比如每个技能必须有清晰的描述、完整的输入输出定义、以及至少一个使用示例。没有这些技能库很快就会变成一堆没人敢用的“黑盒”。6. 常见问题与排查技巧实录6.1 技能不触发或误触发怎么办这是最常见的问题。排查思路是先从触发条件入手确认关键词和文件模式是否匹配当前场景。可以在技能框架里开启调试日志看看每次用户输入时各个技能的触发判断结果。如果是不触发检查关键词是否被正确分词。中文分词有时候会把“格式化代码”拆成“格式化”和“代码”如果技能只匹配“格式化”那没问题但如果匹配的是“格式化代码”这个完整短语就可能漏掉。建议关键词尽量用短词不要用长短语。如果是误触发增加文件模式或上下文条件的限制。比如一个“生成文档”的技能如果只靠“文档”这个词触发用户在讨论项目文档结构时也会激活。加上“当前目录存在 docs 文件夹”这个条件就能过滤掉大部分误触发。6.2 工具调用失败的排查路径工具调用失败的原因很多我整理了一个排查顺序按这个顺序走基本能定位到问题。排查步骤检查内容常见问题1命令是否存在工具未安装或不在 PATH 中2参数是否正确变量替换后命令格式错误3权限是否足够文件只读或目录无写入权限4网络是否通畅需要下载依赖或调用远程服务5资源是否充足内存不足或磁盘空间不够这个顺序的逻辑是从内到外、从简单到复杂。大部分问题在前两步就能发现。我遇到最多的情况是变量替换后命令里多了空格或少了引号导致 shell 解析出错。解决办法是在技能定义里对变量做预处理或者用更严格的引用方式。6.3 上下文窗口不足的应对方法长时间使用 AI 编程工具上下文窗口被占满是迟早的事。Claude Code 和 Codex CLI 都有压缩历史的功能但压缩意味着信息丢失有时候会丢失关键上下文。我的应对策略是分层管理上下文。把信息分成“必须保留”和“可以丢弃”两类。必须保留的包括当前任务描述、关键代码片段、错误信息可以丢弃的包括早期的探索性对话、已经解决的中间问题。具体操作上我会在技能定义里加一个上下文清理步骤在任务开始前自动清理无关历史。另外Codex CLI 的/compact命令要善用但不要等到窗口快满了才用而是在一个阶段性任务完成后主动压缩保留最重要的部分。6.4 技能执行结果不符合预期的调试方法有时候技能跑完了没报错但结果就是不对。这种情况最难排查因为问题可能出在任何一个环节。我的方法是“分段验证”。把技能的执行步骤拆开一步一步手动执行看哪一步的输出开始偏离预期。比如一个“生成 API 文档”的技能先手动执行代码解析步骤看解析出的接口列表对不对再手动执行模板渲染步骤看渲染结果对不对。定位到具体步骤后再深入排查该步骤的输入和逻辑。另一个技巧是增加中间输出。在技能定义里每个步骤都可以配置输出中间结果。虽然会增加一些日志量但排查问题时非常有用。我通常会在开发阶段开启所有中间输出稳定后再关掉。7. 进阶玩法技能组合与自动化工作流7.1 技能链式调用的设计模式单个技能能做的事情有限真正的威力在于技能组合。superpowers 框架支持技能链式调用——一个技能的输出可以作为下一个技能的输入。举个实际例子。我定义了一个“代码审查”技能链第一个技能扫描代码变更提取出修改的函数和类第二个技能对每个修改点生成审查意见第三个技能把审查意见汇总成报告并发送到团队频道。三个技能串联起来就形成了一个自动化的代码审查工作流。链式调用的关键在于接口设计。每个技能的输出格式要标准化下一个技能才能正确解析。我通常用 JSON 作为技能间传递数据的格式结构清晰解析方便。7.2 条件分支与循环处理不是所有工作流都是线性的。有时候需要根据条件走不同的分支或者对一组文件循环执行某个技能。条件分支的实现方式是在技能定义里加condition字段steps: - action: check_test_coverage condition: {{coverage}} 80 next: generate_tests - action: report_success condition: {{coverage}} 80这个例子的逻辑是如果测试覆盖率低于 80%就生成测试否则直接报告成功。条件表达式支持基本的比较和逻辑运算。循环处理则通过foreach字段实现steps: - action: process_file foreach: {{target_files}} command: python process.py {{item}}foreach会遍历target_files列表对每个文件执行一次process_file动作。{{item}}是当前迭代的元素。7.3 把技能框架接入日常开发流程技能框架搭好之后怎么让它真正融入日常开发而不是变成一个“玩具”我的经验是从高频、重复、规则明确的任务入手。比如每天都要做的代码格式化、提交信息生成、依赖更新检查这些任务规则清晰适合做成技能。一开始不要贪多先做两三个用顺了再扩展。我见过有人一口气定义了二十多个技能结果大部分都没用过反而增加了维护负担。另一个建议是让技能“可发现”。在团队里维护一个技能清单说明每个技能做什么、怎么触发、有什么注意事项。新成员入职时这份清单就是他们上手 AI 辅助开发的入门指南。7.4 技能库的版本管理与团队协作当技能数量多起来之后版本管理就变得重要了。我的做法是给技能库打标签比如v1.0表示稳定版v1.1-beta表示测试版。项目引用技能库时指定版本号避免因为技能更新导致现有工作流突然失效。团队协作方面技能库的修改走代码审查流程。每个新技能或技能修改都要经过至少一个人 review确保定义清晰、逻辑正确、没有安全隐患。特别是涉及终端命令执行的技能一定要审查命令的安全性避免注入风险。注意技能定义里如果包含用户输入直接拼接成终端命令的情况务必做转义处理。这是安全底线不能妥协。8. 我踩过的坑与实测有效的技巧8.1 技能粒度太粗和太细都不好刚开始设计技能时我犯过一个错误把技能做得太“大”。一个技能里塞了十几个步骤从代码分析到重构到测试到提交全包了。结果就是调试极其困难任何一步出问题都要从头跑一遍而且技能复用性很差——换个项目流程就不一样了。后来我调整为“小技能”策略。每个技能只做一件事比如“提取函数签名”“替换导入路径”“生成测试桩”。小技能容易调试、容易复用、容易组合。需要复杂流程时用技能链把它们串起来。这个调整之后技能库的可用性明显提升。但也不能太细。如果一个技能只是“在文件末尾加一个换行符”那就没必要单独做成技能了直接写个脚本更简单。判断标准是这个操作是否会在多个场景下重复出现是否有明确的输入输出如果答案是肯定的就值得做成技能。8.2 日志与可观测性的重要性技能框架运行在 AI 工具之上出问题时往往看不到底层发生了什么。没有日志排查就像盲人摸象。我在技能定义里强制要求每个步骤都输出日志包括输入参数、执行结果、耗时、错误信息。日志的格式也有讲究。我推荐用结构化日志JSON 格式方便后续用工具分析和检索。比如{ timestamp: 2024-01-15T10:30:00Z, skill: format-python, step: run_formatter, input: {files: [a.py, b.py]}, result: success, duration_ms: 1250 }这种日志看起来啰嗦但当你需要排查“为什么昨天还好好的技能今天失败了”这类问题时结构化日志能帮你快速定位到具体是哪个文件、哪个步骤、什么时间出的问题。8.3 性能优化的几个实用手段技能执行慢是另一个常见痛点。我总结了几条优化经验。第一减少不必要的工具调用。每次调用终端命令都有启动开销能合并的命令就合并。比如格式化多个文件不要循环调用black而是一次性传入所有文件路径。第二缓存重复计算的结果。如果多个技能都需要项目结构信息不要每次都重新扫描目录缓存起来复用。第三并行执行独立任务。如果技能链中有多个互不依赖的步骤可以并行执行。比如同时生成文档和运行测试两者没有依赖关系并行能节省不少时间。第四合理设置超时。有些工具调用可能卡住设置合理的超时时间比如 30 秒能避免整个技能链被阻塞。8.4 安全边界哪些事不该让技能自动做自动化很爽但有些操作必须保留人工确认环节。我的原则是任何不可逆的操作都要有确认步骤。具体来说删除文件、强制推送代码、修改生产环境配置、执行数据库迁移这些操作即使技能支持也应该在最后一步弹出确认提示让人工决定是否继续。我见过有人写了一个“自动清理无用分支”的技能结果因为判断逻辑有 bug把正在开发的分支删了损失了好几天的工作。另一个安全边界是敏感信息的处理。技能定义里不要硬编码 API 密钥、数据库密码这类信息应该通过环境变量或密钥管理服务注入。技能日志里也要过滤掉敏感信息避免泄露。9. 从工具到方法论superpowers 带来的思维转变用了几个月 superpowers 框架之后我发现自己对 AI 辅助开发的理解发生了变化。以前我把 AI 当成一个“更聪明的搜索引擎”问它问题等它回答。现在我把 AI 当成一个“可编程的协作伙伴”我定义技能和工作流它负责执行。这个转变的核心在于从“对话式交互”转向“工程化协作”。对话式交互的问题是每次都要重新描述需求效率低且不稳定。工程化协作则是把需求固化成技能一次定义多次复用结果可预期。对于团队来说这种思维转变的价值更大。当每个人都用自己的方式跟 AI 对话时产出质量参差不齐。但当团队有一套共享的技能库时AI 辅助开发就变成了标准化的流程新人能快速上手老人能持续优化。我目前还在探索的一个方向是“自适应技能”——技能根据项目的历史数据和执行反馈自动调整参数。比如格式化技能根据项目代码风格自动选择配置测试生成技能根据历史 bug 分布调整测试重点。这个方向还在早期但我觉得挺有意思。最后分享一个小心得不要试图一次性把技能库建得很完美。先跑起来用起来在用的过程中发现痛点再针对性地优化。我最初的几个技能现在回头看都很粗糙但正是它们让我理解了技能框架的运作方式才有了后面更成熟的设计。工具是死的用法是活的找到适合自己团队的节奏最重要。