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

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后，我的第一反应是：这东西不是又一个花哨的提示词合集，它更像是一套给 AI 编程助手用的“技能操作系统”。

先把概念说清楚。所谓agentic skills framework，直译过来是“智能体技能框架”，但这么翻译太干巴了。你可以把它理解成：以前我们用 Claude Code、Codex CLI 这类工具，是把它当成一个“什么都能聊但什么都不精”的实习生；而 superpowers 做的事情，是给这个实习生配了一整套标准作业程序（SOP），让它知道在什么场景下该调用什么技能、按什么顺序执行、产出什么样的结果。

这套框架的核心价值在于三个字：可复用。我见过太多人用 Claude Code 的方式是——每次遇到问题，现场想提示词，现场调参数，现场试错。今天调通了一个“帮我重构这个函数”的流程，明天换个项目又得从头来一遍。superpowers 想解决的，就是这种“一次性提示词”的浪费。它把常见的软件开发动作——代码审查、测试生成、重构、文档撰写、依赖分析——抽象成一个个独立的 skill（技能），每个 skill 有明确的输入输出、执行步骤和验收标准。

那它跟普通的 prompt template 有什么区别？区别大了。普通的提示词模板是静态的，你填个变量进去，它给你一段文字。而 superpowers 里的 skill 是带执行逻辑的。一个 skill 可以包含多个步骤，可以在中间调用工具，可以根据上一步的结果决定下一步走哪条分支。这就从“模板”升级到了“流程”。

适合谁来用？我的判断是三类人。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师，你们已经过了“哇 AI 能写代码”的新鲜期，现在需要的是稳定、可重复的工作流。第二类是技术团队的负责人，你们在考虑怎么把 AI 编程工具规范化地引入团队，superpowers 提供了一套可以参考的方法论。第三类是对 agentic 工作流感兴趣的产品经理或技术写作者，你们不需要写代码，但需要理解这套框架的设计思路，因为它代表了一种新的“人机协作”范式。

我后面会从设计思路、核心机制、实操配置、常见坑四个维度，把这套框架拆开讲。文章会比较长，因为我不想只给你一个“安装完事”的教程——那种内容网上已经够多了。我想讲的是：为什么这么设计、每一步背后的考量是什么、我在实际配置过程中踩了哪些坑、以及怎么根据你自己的技术栈做定制。

2. 核心设计思路拆解：为什么是“技能”而不是“提示词”

2.1 从提示词工程到技能工程的范式转移

过去两年，大家聊 AI 编程，聊的都是“提示词工程”（Prompt Engineering）。怎么把需求描述清楚、怎么给例子、怎么设定角色，这些技巧确实有用，但有个根本问题：提示词是一次性的。你写了一段很精妙的提示词，让 AI 帮你完成了一次复杂的重构，但下次遇到类似任务，你还得重新写一遍，或者从聊天记录里翻出来复制粘贴。

superpowers 的设计者显然想明白了这件事。他们把“技能”作为基本单元，而不是“提示词”。一个 skill 包含的不只是文字描述，还有：

• 触发条件：什么情况下应该激活这个技能
• 前置检查：执行前需要确认哪些信息
• 执行步骤：分几步走，每步做什么
• 工具调用：需要用到哪些外部工具或命令
• 输出格式：产出物应该长什么样
• 验收标准：怎么判断这个技能执行成功了

这六个要素加起来，才构成一个完整的 skill。你可以把它类比成工厂里的“工位操作手册”——不是告诉你“要细心”，而是告诉你“第一步拿扳手，第二步拧三圈，第三步用卡尺量”。

2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体

热词里反复出现 Claude Code 和 Codex CLI，这不是偶然。superpowers 这套框架要落地，必须依附在一个能执行终端命令、能读写文件、能调用外部工具的 agent 环境里。纯聊天窗口做不到，因为聊天窗口没有“执行”能力。

Claude Code 和 Codex CLI 恰好满足这几个条件：它们能直接操作文件系统、能跑 shell 命令、能读取项目上下文。更重要的是，它们都支持一定程度的“配置扩展”——你可以通过配置文件或插件机制，注入自定义的行为逻辑。superpowers 就是利用了这个扩展点，把技能框架挂载进去。

我实测下来，Claude Code 在技能编排的灵活性上更好一些，因为它的工具调用协议更开放，你可以比较方便地定义“先读文件、再分析、再写回”这样的多步流程。Codex CLI 的优势在于命令行的交互更直接，适合做那种“一条命令触发一个技能”的轻量场景。

2.3 框架的分层结构：技能层、编排层、执行层

把 superpowers 拆开看，它其实是三层结构。

技能层是最上面一层，也是用户直接接触的部分。每个 skill 是一个独立的 Markdown 文件或者 YAML 配置，里面写清楚了前面说的六个要素。这一层的设计原则是“高内聚”——一个 skill 只做一件事，比如“生成单元测试”就是一个 skill，“重构函数”是另一个 skill，不要混在一起。

编排层是中间层，负责决定“什么时候用哪个技能”。这一层可以很简单，比如根据用户的自然语言输入匹配关键词；也可以很复杂，比如根据当前项目的文件类型、Git 状态、测试覆盖率来决定。superpowers 默认提供了一套基于规则的编排逻辑，但留了扩展接口，你可以接入自己的路由策略。

执行层是最下面一层，直接跟 Claude Code 或 Codex CLI 的运行时打交道。这一层处理的是具体的工具调用、文件读写、命令执行。它的设计目标是“可替换”——今天用 Claude Code 执行，明天想换成别的 agent 环境，理论上只需要改执行层的适配器。

这种分层的好处是：你改技能层不会影响执行层，换执行环境不用重写技能。我在实际配置的时候，就是先把技能层写清楚，再慢慢调编排规则，最后才去折腾执行层的适配。顺序反了会很难受。

2.4 与传统脚本自动化的本质区别

有人可能会问：这不就是 shell 脚本加了个 AI 壳吗？我一开始也这么想，但用下来发现区别很大。

传统脚本是确定性的：你写if [ -f "test.py" ]; then pytest; fi，它永远按这个逻辑走。superpowers 的技能是概率性的：你告诉它“检查这个函数的边界条件”，它会根据代码内容动态决定检查哪些边界、生成哪些测试用例。这种灵活性是脚本给不了的。

但概率性也带来了新问题：结果不稳定。同一个技能，今天跑和明天跑，产出可能不一样。superpowers 的应对方式是引入“验收标准”——每个技能执行完后，会有一个自检步骤，检查产出是否满足预设条件。不满足就重试或者报错。这个机制很关键，后面讲实操的时候我会详细说。

3. 核心机制深度解析：技能定义、编排逻辑与执行反馈

3.1 一个 skill 的完整解剖：以“代码审查”为例

光讲概念太虚，我拿一个具体的 skill 来拆。假设我们要定义一个“代码审查”技能，它应该包含哪些部分？

首先是元信息：技能名称、版本号、适用场景描述。这部分看起来简单，但很重要——名称要唯一，版本号要能追溯，场景描述要能让编排层准确匹配。

然后是触发条件。代码审查技能什么时候激活？我的配置是：当用户输入包含“review”“审查”“检查这段代码”等关键词，且当前上下文中有未提交的 Git 变更时，自动激活。这里有个细节：我加了“未提交的变更”这个条件，因为如果代码已经提交了，审查的意义就不一样了（应该走“提交后审查”流程）。

接下来是前置检查。执行审查之前，需要确认几件事：当前目录是不是 Git 仓库、有没有未提交的变更、变更涉及哪些文件、这些文件是什么语言。这些信息决定了后续审查的重点。比如 Python 文件和 TypeScript 文件的审查要点完全不同。

执行步骤是核心。我的配置分了四步：

1. 读取变更文件的 diff，识别改动的函数和类
2. 对每个改动单元，检查命名规范、边界条件、错误处理、性能隐患
3. 生成审查意见，按严重程度分级（阻塞、建议、提示）
4. 输出结构化报告，包含文件路径、行号、问题描述、修改建议

工具调用方面，这个技能需要用到git diff、文件读取、以及一个可选的静态分析工具（比如 Python 的pylint或 TypeScript 的eslint）。我把静态分析设为可选，因为不是所有项目都配了这些工具，强制依赖会导致技能在干净环境里跑不起来。

输出格式我定的是 Markdown 表格，三列：位置、问题、建议。这样可以直接贴到 PR 评论里。

验收标准有三条：报告非空、每个问题都有具体行号、阻塞级问题不超过总问题数的 30%（如果超过，说明代码质量太差，应该建议整体重构而不是逐条修）。

你看，一个完整的 skill 就是这么细。写的时候很费劲，但写完一次，后面所有项目都能复用。

3.2 编排逻辑：规则匹配与上下文感知的平衡

编排层要解决的核心问题是：用户说了一句话，怎么知道该调用哪个技能？

最笨的办法是关键词匹配。用户说“帮我审查代码”，匹配到“审查”，调用代码审查技能。但这种方法很脆——用户说“看看这段代码有没有问题”，就匹配不上了。

superpowers 默认的编排逻辑是“关键词 + 上下文”的混合模式。关键词负责粗筛，上下文负责精排。具体来说：

• 先用关键词把候选技能缩小到 3-5 个
• 然后检查当前上下文（文件类型、Git 状态、最近操作历史），给每个候选技能打分
• 选分数最高的执行

我在这基础上加了一条规则：如果用户明确说了技能名称（比如“用 code-review 技能”），直接跳过匹配，强制执行指定技能。这在调试的时候特别有用。

还有一个坑要注意：技能冲突。比如“重构”和“代码审查”都可能被“帮我优化这段代码”触发。我的处理方式是给技能设优先级，重构的优先级高于审查，因为重构本身包含了审查步骤。如果两个技能优先级相同，就弹出来让用户选。

3.3 执行反馈循环：怎么让技能越用越准

superpowers 有一个我特别欣赏的设计：执行反馈记录。每次技能执行完，框架会把这次执行的上下文、选择的技能、执行结果、用户反馈（如果有）记下来。这些记录可以用来优化编排逻辑。

举个例子。我一开始配置的“生成测试”技能，总是被“写个测试”这句话触发。但后来发现，用户说“写个测试”的时候，有时候是想生成单元测试，有时候是想写集成测试。光靠关键词分不出来。于是我加了一个上下文判断：如果当前文件是test_*.py或者*.test.ts，走单元测试技能；如果当前目录有integration或e2e字样，走集成测试技能。这个规则就是从执行记录里总结出来的。

反馈循环的另一个用途是技能迭代。如果一个技能连续多次执行失败，或者用户频繁手动修改产出，说明这个技能的步骤设计有问题。我会定期翻执行记录，把失败率高的技能拿出来重新设计。

3.4 技能之间的依赖与组合

单个技能能做的事有限，真正强大的是技能组合。superpowers 支持在技能定义里声明依赖——比如“重构”技能依赖“代码审查”技能和“测试生成”技能。

依赖关系有两种：串行依赖和并行依赖。串行依赖是“必须先做 A 才能做 B”，比如先审查再重构。并行依赖是“A 和 B 可以同时做”，比如同时生成单元测试和集成测试。

我在配置重构技能的时候，把它设计成了串行依赖：先调审查技能找出问题，再根据问题类型决定重构策略，最后调测试技能验证重构没破坏功能。整个流程跑下来，比手动一步步操作快很多，而且不会漏步骤。

但依赖多了也有问题：执行时间变长。一个重构任务如果串了三个技能，每个技能平均跑 30 秒，总共就要一分半。如果中间某个技能失败，整个流程就卡住了。我的应对策略是给每个技能设超时，超时就跳过并记录，不让它阻塞整个流程。

4. 实操配置全流程：从零搭建你的技能框架

4.1 环境准备：Claude Code 与 Codex CLI 的安装要点

先说 Claude Code 的安装。官方文档给的步骤很简洁，但实际装的时候有几个坑。

在 macOS 上，如果你用 Homebrew，一条命令就能装好。但要注意 Node.js 的版本——Claude Code 要求 Node 18 以上，我建议直接用 nvm 管理 Node 版本，避免系统自带的旧版本冲突。装完之后跑claude --version确认一下。

Ubuntu 上的安装稍微麻烦一点。如果你用的是 22.04 或 24.04，apt 源里的 Node 版本可能不够新。我的做法是先装 nvm，再用 nvm 装 Node 20 LTS，然后再装 Claude Code。另外 Ubuntu 上要注意权限问题——如果你用 sudo 装全局包，后面跑的时候可能会遇到权限报错。建议用npm config set prefix把全局包目录设到用户目录下。

Windows 用户要注意：热词里有人提到“由于与64位版本的 Windows 不兼容”，这个问题通常出现在旧版 Node 上。解决办法是装 64 位的 Node，并且确保没有同时装 32 位和 64 位两个版本。如果还是不行，建议用 WSL2，在 Linux 子系统里装，体验会好很多。

Codex CLI 的安装相对简单，它主要是通过 npm 分发。装完之后用codex --help看一下命令列表。热词里有人问“codex cli 命令哪些 /compact /model /resume”，这几个是常用命令：/compact压缩上下文、/model切换模型、/resume恢复上次会话。我建议先把这几个命令练熟，后面配置技能的时候会经常用到。

4.2 技能目录结构设计：怎么组织你的 skills

装好工具之后，下一步是设计技能目录。superpowers 默认会从几个位置加载技能：项目根目录下的.superpowers/skills/、用户主目录下的~/.superpowers/skills/、以及框架自带的技能库。

我的建议是分三层组织：

• 全局技能放在~/.superpowers/skills/，放那些所有项目通用的，比如代码审查、提交信息生成、文档撰写
• 项目技能放在项目根目录的.superpowers/skills/，放这个项目特有的，比如“生成 API 文档”“检查数据库迁移”
• 实验技能放在一个单独的experimental/目录，还没稳定下来的先放这里，不参与自动编排

每个技能一个目录，目录名就是技能名。目录里面至少有一个skill.md或者skill.yaml，描述技能定义。如果有辅助脚本，也放在同一个目录下。

我踩过的一个坑是：技能名用了中文。框架本身支持，但有些工具链在处理中文路径时会出问题。后来我全部改成英文加连字符，比如code-review、test-gen、refactor。这样兼容性最好。

4.3 编写第一个技能：从“提交信息生成”开始

如果你刚开始用 superpowers，我建议从最简单的技能入手：提交信息生成。这个技能逻辑简单、依赖少、见效快，适合用来熟悉框架的写法。

技能定义大概长这样（我用 YAML 格式举例，因为比 Markdown 更好解析）：

name: commit-message version: 1.0.0 description: 根据 Git 暂存区的变更生成规范的提交信息 triggers: - "生成提交信息" - "写 commit message" - "commit" preconditions: - check: git rev-parse --is-inside-work-tree message: 当前目录不是 Git 仓库 - check: git diff --cached --quiet expect: false message: 暂存区没有变更 steps: - action: run command: git diff --cached --stat save_as: diff_stat - action: run command: git diff --cached save_as: diff_content - action: prompt template: | 根据以下变更生成提交信息，遵循 Conventional Commits 规范： {{diff_content}} 要求：类型（feat/fix/refactor/docs/test/chore）+ 范围 + 简短描述 save_as: message output: format: text save_to: .git/COMMIT_EDITMSG validation: - check: message 长度在 10-72 字符之间 - check: message 符合 Conventional Commits 格式

这个技能跑起来的效果是：你敲一句“生成提交信息”，它自动读暂存区的 diff，生成一条规范的 commit message，直接写进.git/COMMIT_EDITMSG。你只需要确认一下，然后git commit就行。

我实测下来，这个技能能省掉大概 70% 的提交信息编写时间。而且因为格式统一，团队的提交历史看起来清爽很多。

4.4 编排规则配置：让技能在正确的时机触发

技能写好了，还得告诉框架什么时候用它。编排规则的配置文件通常叫orchestrator.yaml或者routing.yaml，放在.superpowers/目录下。

我的配置逻辑是这样的：

rules: - match: keywords: ["提交", "commit", "message"] context: git_repo: true staged_changes: true skill: commit-message priority: 10 - match: keywords: ["审查", "review", "检查"] context: git_repo: true has_changes: true skill: code-review priority: 8 - match: keywords: ["测试", "test"] context: file_pattern: "*.py" skill: test-gen-python priority: 7

这里的关键是context部分。光靠关键词匹配会误触发，加上上下文条件就准多了。比如“提交”这个词，如果当前目录不是 Git 仓库，就不该触发提交信息技能。

优先级的作用是解决冲突。数字越大优先级越高。我把提交信息设为 10，因为它最明确、最不容易误触发。代码审查设为 8，测试生成设为 7。

4.5 与 VS Code 的集成配置

很多人是在 VS Code 里用 Claude Code 的，所以集成配置也得说一下。

VS Code 的 Claude Code 插件装好之后，需要在设置里配置两件事：一是 Claude Code 的可执行文件路径，二是技能目录的位置。路径配置不对的话，插件会提示“找不到 Claude Code”。

我的配置是：

{ "claudeCode.executablePath": "/Users/yourname/.nvm/versions/node/v20.11.0/bin/claude", "claudeCode.skillsPath": "${workspaceFolder}/.superpowers/skills", "claudeCode.autoActivate": true }

autoActivate设为 true 之后，插件会根据编排规则自动激活技能，不用手动敲命令。这个在写代码的时候特别方便——你改完一个函数，直接说“审查一下”，它就知道该调哪个技能。

有个细节要注意：如果你同时装了 Claude Code 和 Codex CLI 的插件，可能会冲突。我的做法是只装一个，另一个用命令行。这样避免快捷键和命令面板的混乱。

4.6 接入本地模型：以 LM Studio 为例

热词里有人问“claude code 调用 lmstudio 的本地模型”，这个需求我理解——有些场景下不想用云端模型，想跑本地模型。配置方法是改 Claude Code 的模型端点。

LM Studio 启动后，默认会在http://localhost:1234提供一个兼容 OpenAI 协议的 API。你需要在 Claude Code 的配置里把模型端点指过去：

export CLAUDE_CODE_API_BASE="http://localhost:1234/v1" export CLAUDE_CODE_MODEL="local-model-name"

然后在 LM Studio 里加载你想要的模型，确保它支持工具调用（function calling）。不是所有本地模型都支持工具调用，这点很关键——superpowers 的技能执行依赖工具调用，模型不支持的话技能跑不起来。

我实测下来，本地模型在简单技能上表现还行，比如提交信息生成、文档撰写。但复杂技能（比如代码审查、重构）还是云端模型更稳。本地模型的上下文窗口和推理能力是瓶颈。

4.7 第三方 API 接入的注意事项

如果你不想用官方 API，想接第三方兼容端点，有几个坑要注意。

第一是协议兼容性。有些第三方端点号称兼容 OpenAI 协议，但实际用的时候会发现工具调用的格式对不上。解决办法是先跑一个最简单的技能测试，确认工具调用能正常工作。

第二是速率限制。第三方端点通常有更严格的速率限制，技能连续执行的时候容易被限流。我的做法是在技能配置里加一个重试机制，遇到 429 错误就等几秒重试。

第三是模型名称映射。不同厂商的模型名称不一样，你需要把技能里写的模型名称映射到实际可用的名称。这个映射关系最好放在一个单独的配置文件里，方便切换。

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

5.1 技能不触发或触发错误

这是最常见的问题。表现是：你说了“审查代码”，但框架没反应，或者调用了错误的技能。

排查思路分三步。第一步，检查关键词是否匹配。把你的输入和技能定义里的triggers对比一下，看看有没有拼写差异或者同义词缺失。我遇到过用户说“检查代码”，但技能只配了“审查代码”，结果匹配不上。解决办法是在 triggers 里加同义词。

第二步，检查上下文条件。如果技能配了git_repo: true，但当前目录不是 Git 仓库，技能就不会触发。用git rev-parse --is-inside-work-tree确认一下。

第三步，检查优先级冲突。如果两个技能都匹配上了，优先级高的会执行。如果你期望的技能没执行，看看是不是被别的技能抢了。可以在配置里打开调试日志，看框架实际选了哪个技能。

5.2 执行超时与中断处理

技能执行到一半卡住，或者超时报错，这个也很常见。原因通常是某个步骤在等外部响应，比如网络请求或者大文件读取。

我的处理方式是在技能定义里给每个步骤设超时：

steps: - action: run command: some-command timeout: 30s on_timeout: skip

on_timeout: skip表示超时后跳过这一步，继续执行后面的。这样不会因为一个步骤卡住导致整个技能失败。但要注意，跳过的步骤可能会影响后续步骤的输入，所以最好在技能设计的时候就考虑好降级方案。

5.3 输出格式不符合预期

技能跑完了，但产出格式乱七八糟，没法直接用。这个问题通常出在提示词模板上。

我的经验是：给例子比给描述更有效。与其写“生成一个 Markdown 表格”，不如直接给一个表格样例，让模型照着填。模型对格式的模仿能力很强，给个例子它就能学会。

另外，输出格式的验收标准要写具体。不要写“格式正确”，要写“包含三列：位置、问题、建议；每行以|开头和结尾”。这样验收的时候才能自动检查。

5.4 技能之间的数据传递失败

当一个技能依赖另一个技能的输出时，数据传递容易出问题。比如审查技能输出了一个 JSON，重构技能读的时候解析失败。

排查方法是：在技能之间加一个“数据校验”步骤。审查技能输出后，先检查 JSON 是否合法，不合法就报错，而不是直接传给下一个技能。这样问题定位更准。

我还会在技能配置里明确声明输入输出的 schema，这样框架可以在传递数据的时候做类型检查。虽然多写一点配置，但省去了很多调试时间。

5.5 常见问题速查表

5.6 几个我踩过的坑和对应的技巧

坑一：技能目录放错位置。我一开始把技能放在项目根目录的skills/下，但框架默认只读.superpowers/skills/。结果技能一直不加载。后来看了日志才发现路径不对。建议装完框架后先跑一个list-skills命令，确认技能能被识别。

坑二：YAML 缩进错误。YAML 对缩进极其敏感，多一个空格少一个空格都会导致解析失败。我建议用 VS Code 的 YAML 插件，它会实时检查缩进。另外，写完技能定义后，用yamllint跑一遍，能提前发现很多问题。

坑三：技能名冲突。全局技能和项目技能重名的时候，框架的行为不确定。我的做法是给项目技能加前缀，比如myproject-code-review，避免冲突。

坑四：忘记清理实验技能。实验技能如果没及时清理，可能会被编排层误触发。我现在的做法是给实验技能加一个enabled: false标记，确认稳定后再改成 true。

坑五：过度依赖自动编排。自动编排很方便，但有时候不如手动指定准确。我现在养成了一个习惯：复杂任务手动指定技能链，简单任务才用自动编排。这样结果更可控。

6. 技能框架的扩展与定制：让它真正长在你自己的技术栈上

6.1 自定义技能的三个层次

superpowers 提供的默认技能库覆盖了通用场景，但每个团队的技术栈不一样，肯定需要定制。我把定制分成三个层次，由浅入深。

第一层是改提示词。默认技能的提示词是通用的，你可以改成更贴合自己团队的风格。比如代码审查技能，默认的审查要点是通用的，你可以加上团队特有的规范——比如“所有公开函数必须有类型注解”“禁止使用any类型”。改提示词不需要写代码，改 YAML 就行，门槛最低。

第二层是加步骤。默认技能的步骤可能不够用，你可以在中间插入自定义步骤。比如在代码审查之前，先跑一遍团队的 lint 脚本，把 lint 结果作为审查的输入之一。加步骤需要理解技能的输入输出流转，但也不需要写代码。

第三层是写适配器。如果默认的执行层不支持你的某个工具，你需要写一个适配器。比如你们团队用的是一个自研的静态分析工具，框架默认不支持，你就得写一个适配器把它的输出转成框架能理解的格式。这一层需要写代码，但一旦写好，后面所有技能都能用。

6.2 把团队规范编码进技能

这是我觉得 superpowers 最有价值的地方：把团队规范从文档变成可执行的技能。

以前团队规范写在 Confluence 里，没人看。现在把规范写成技能，每次代码审查自动执行。比如我们团队的规范有一条：“所有 API 接口必须有错误处理，且错误信息不能暴露内部实现细节。”这条规范以前靠人肉检查，现在写进审查技能，自动检查每个接口的错误处理分支。

具体做法是在审查技能的提示词里加上这条规范，并且在验收标准里加一条：“检查每个 API 接口是否有 try-catch 或等效的错误处理”。这样审查报告里会明确列出不符合规范的接口。

6.3 技能版本管理与团队协作

技能多了之后，版本管理就成了问题。我的做法是用 Git 管理技能目录，每个技能一个文件，改动走 PR 流程。

技能文件的版本号遵循语义化版本：改提示词是 patch，加步骤是 minor，改输入输出 schema 是 major。这样团队成员升级技能的时候，能清楚知道会不会破坏现有流程。

团队协作方面，我建议指定一个“技能维护者”角色，负责审核技能改动、解决技能冲突、维护编排规则。不然每个人都往技能库里加东西，很快就乱了。

6.4 性能优化：减少不必要的技能调用

技能调用是有成本的——每次调用都要消耗 token，都要花时间。所以优化目标很明确：能不用就不用，能用简单的就不用复杂的。

我的优化策略有三条。第一条，给技能加“快速路径”。比如提交信息生成技能，如果变更只涉及一个文件且改动小于 10 行，直接走模板生成，不调模型。第二条，缓存技能结果。同一个文件、同样的变更，审查结果可以缓存一段时间，避免重复审查。第三条，合并相似技能。如果两个技能有 80% 的步骤重合，就合并成一个，用参数区分。

6.5 后续扩展方向：从个人工具到团队基础设施

如果你已经把 superpowers 用起来了，下一步可以考虑这几个扩展方向。

方向一是接入 CI/CD。把技能框架挂到 CI 流程里，每次 PR 自动跑代码审查和测试生成，审查结果直接贴到 PR 评论。这样技能就从“个人辅助”变成了“团队质量门禁”。

方向二是做技能市场。团队内部建一个技能仓库，大家把自己写的技能贡献出来，互相复用。我们团队现在有 30 多个技能，覆盖了从代码审查到部署检查的各个环节。

方向三是接更多 agent 环境。现在主要跑在 Claude Code 和 Codex CLI 上，未来可以适配更多的 agent 运行时。技能层和执行层分离的设计，让这种适配变得相对容易。

方向四是做技能效果度量。记录每个技能的执行次数、成功率、用户采纳率，用数据驱动技能优化。哪些技能没人用，就下线；哪些技能经常失败，就重构。

我个人在实际操作中的体会是，superpowers 这套框架最大的价值不在于它自带的技能，而在于它提供了一种把开发经验沉淀成可执行资产的方法。以前老工程师的经验在脑子里，带新人的时候靠口传心授。现在可以把这些经验写成技能，新人装好框架就能用。这个转变的意义，比省几行代码大得多。

最后再分享一个小技巧：如果你刚开始用，不要一上来就写复杂技能。先写三个最简单的——提交信息生成、代码格式化检查、文档拼写检查。这三个技能逻辑简单、依赖少、见效快，能帮你快速熟悉框架的写法。等这三个跑顺了，再逐步加复杂度。我见过太多人一上来就想写一个“全自动重构”技能，结果卡在配置上，最后放弃了。循序渐进，比一步到位靠谱。