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

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后，我的第一反应是：这东西不是又一个花哨的提示词合集，它更像是一套软件工程方法论的重新封装——把“怎么让 AI 编程助手真正干活”这件事，从零散的技巧升级成了有结构、可复用、可组合的技能体系。

如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程代理，大概率会遇到一个共同的痛点：模型本身很强，但每次都要从头解释项目背景、代码规范、测试要求，稍微复杂一点的任务就“跑偏”。superpowers 想解决的正是这个问题——它把常见的开发动作（写测试、做代码审查、调试、重构、写文档）抽象成一个个独立的 skill，让 agent 按需加载、按流程执行。说白了，它给 AI 编程助手装上了一套“职业素养”。

这篇文章适合三类人看：一是刚接触 Claude Code 或 Codex CLI、还在摸索怎么让 AI 真正帮上忙的新手；二是已经在用这些工具、但觉得效率卡在瓶颈上的中级用户；三是想理解 agentic skills framework 设计思路、准备自己搭一套类似体系的技术负责人。我会从设计思路、核心机制、实操落地、常见坑四个维度拆开讲，尽量把每个“为什么这么设计”说清楚，让你看完能直接抄作业。

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

2.1 从提示词工程到技能工程，差的是“可组合性”

大部分人用 AI 编程工具的方式，还停留在“写一段详细提示词，然后祈祷模型理解”。这种方式在单次任务里勉强够用，但一旦任务变复杂——比如“给这个模块加个功能，顺便补测试，再更新文档”——提示词就会变成一锅粥，模型很容易顾此失彼。

superpowers 的核心洞察是：复杂开发任务不该用一个巨型提示词解决，而应该拆成多个独立技能，按依赖关系组合执行。这跟软件工程里“高内聚、低耦合”的思路是一脉相承的。每个 skill 只负责一件事，比如“写单元测试”就是一个 skill，“做代码审查”是另一个 skill。agent 在执行任务时，先判断需要哪些 skill，再按顺序调用。

这种设计的好处很直接：技能可以复用。你今天给项目 A 写的“Python 测试规范”skill，明天换个项目只要改改配置就能用。而提示词是一次性的，换个场景就得重写。

2.2 技能的生命周期：发现、加载、执行、验证

我拆过几个类似的 agentic skills framework，发现它们基本都遵循一个四阶段生命周期。理解这个生命周期，是用好 superpowers 的前提。

发现阶段：agent 接到任务后，先扫描当前可用的 skill 列表，判断哪些跟任务相关。这一步的关键是 skill 的描述要足够清晰，否则 agent 会漏掉或者误用。我见过有人把 skill 描述写得特别抽象，结果 agent 根本不知道什么时候该调用它。

加载阶段：确定要用的 skill 后，agent 把 skill 的完整内容读进上下文。这里有个工程上的取舍——skill 内容太长会挤占上下文窗口，太短又不够指导执行。我的经验是单个 skill 控制在 500 到 1500 字之间比较合适，核心步骤用列表，细节用引用块。

执行阶段：agent 按照 skill 里定义的步骤操作，可能是读文件、写代码、跑命令。这一步最考验 skill 的“可执行性”——如果 skill 里写的是“优化代码质量”这种模糊指令，agent 就会自由发挥；如果写的是“检查每个函数是否有对应的单元测试，没有则补充”，执行结果就稳定得多。

验证阶段：执行完后，agent 需要确认结果是否符合预期。好的 skill 会自带验证步骤，比如“运行测试套件，确认全部通过”。这一步经常被忽略，但它是保证质量的关键。

2.3 为什么这套框架特别适合 Claude Code 和 Codex CLI

Claude Code 和 Codex CLI 这类工具的共同点是：它们运行在终端里，能直接读写文件、执行命令，具备真正的“动手能力”。这跟纯对话式的 AI 助手有本质区别——后者只能给建议，前者能直接改代码。

superpowers 这类技能框架，恰好放大了这种能力。因为 skill 里可以定义“执行pytest并检查输出”这样的具体动作，agent 就能形成“写代码 → 跑测试 → 根据失败信息修复 → 再跑测试”的闭环。这个闭环是纯对话工具做不到的。

另外，Claude Code 和 Codex CLI 都支持项目级的配置文件，这给 skill 的持久化提供了天然载体。你可以把 skill 定义放在项目根目录的特定文件夹里，agent 每次启动时自动加载。这种“配置即技能”的模式，比每次手动粘贴提示词高效太多。

3. 核心机制深度解析：skill 是怎么被组织和调用的

3.1 skill 的目录结构与命名约定

我参考了几个开源实现，发现它们普遍采用“一个 skill 一个文件夹”的组织方式。文件夹里通常包含一个主描述文件（比如SKILL.md或skill.yaml），以及可选的辅助脚本、模板文件。

命名上有个小技巧：用动词开头，描述具体动作。比如write-unit-test就比testing好，review-pull-request就比code-review好。原因是 agent 在匹配任务时，动词能提供更强的信号。我实测下来，把 skill 名从名词改成动词后，agent 的调用准确率有明显提升。

目录结构大概长这样：

skills/ write-unit-test/ SKILL.md templates/ test-template.py review-code/ SKILL.md checklist.md debug-issue/ SKILL.md

这种结构的优势是每个 skill 自包含，复制到别的项目里也能直接用。辅助文件的存在让 skill 不只是“文字说明”，还能带上实际可用的模板和脚本。

3.2 skill 描述文件的关键字段

一个合格的 skill 描述文件，通常包含这几个部分：触发条件、前置依赖、执行步骤、验证方法、注意事项。我逐个说下每个部分该怎么写。

触发条件要写得具体。不要写“当需要测试时”，而要写“当新增或修改了业务逻辑函数，且该函数没有对应的单元测试时”。前者太宽泛，agent 可能在不该调用的时候调用；后者有明确的判断依据。

前置依赖用来声明这个 skill 需要哪些条件才能执行。比如“写集成测试”这个 skill，可能依赖“本地数据库已启动”。把依赖写清楚，agent 就会先检查依赖，避免执行到一半失败。

执行步骤是核心，建议用有序列表，每步一个动作。动作要具体到“读哪个文件”“运行什么命令”“修改哪部分代码”。我见过写得好的 skill，步骤细到“在tests/目录下创建与源文件同名的测试文件，文件名加test_前缀”。

验证方法定义“怎么算做完了”。可以是“运行pytest tests/且全部通过”，也可以是“检查生成的代码通过 lint 检查”。没有验证方法的 skill，执行结果全靠运气。

注意事项放那些“容易踩坑但又不适合放在步骤里”的内容。比如“如果项目用的是 pytest 而非 unittest，需要调整导入语句”。这类信息放在注意事项里，agent 执行时会参考，但不会打乱主流程。

3.3 技能之间的依赖与组合

单个 skill 能解决的问题有限，真正体现威力的是技能组合。superpowers 这类框架通常支持两种组合方式：串行组合和条件组合。

串行组合就是“做完 A 再做 B”。比如“实现新功能”这个任务，可以拆成write-code→write-unit-test→run-tests→fix-failures四个 skill 依次执行。每个 skill 的输出是下一个的输入，形成流水线。

条件组合是“根据情况选择不同的 skill”。比如debug-issue这个 skill，内部可能根据错误类型分支：如果是语法错误，走fix-syntax；如果是逻辑错误，走analyze-logic。这种组合方式让框架能处理更复杂的场景。

我自己的经验是，先把串行组合用熟，再尝试条件组合。串行组合的逻辑简单，调试起来容易定位问题；条件组合虽然灵活，但一旦分支判断写错，agent 可能走进死胡同。

3.4 上下文管理：skill 加载的取舍

这是很多人忽略但极其重要的一点。Claude Code 和 Codex CLI 的上下文窗口是有限的，如果一次性加载太多 skill，真正用于理解代码的上下文就被挤占了。

我的做法是分层加载：把最常用的核心 skill（比如代码规范、测试要求）放在项目根目录，agent 启动时自动加载；把场景特定的 skill（比如“发布流程”“数据库迁移”）放在子目录，需要时才加载。这样既保证了基础能力随时可用，又不会浪费上下文。

还有一个技巧是用摘要代替全文。对于内容较长的 skill，可以在主文件里放一个简短摘要，详细内容放在辅助文件里，agent 需要时再读取。这跟软件工程里的“懒加载”是一个思路。

4. 实操落地：从零搭一套自己的 superpowers 体系

4.1 环境准备与工具选型

在动手之前，先把基础环境搭好。你需要一个能运行 Claude Code 或 Codex CLI 的终端环境。我用的是 Ubuntu 22.04，Mac 上也没问题，Windows 用户建议用 WSL2，避免路径和权限的坑。

Claude Code 的安装方式，官方文档里有详细说明，核心就是通过包管理器安装命令行工具，然后配置 API 访问。这里有个常见问题：组织账号可能禁用了订阅访问，如果你遇到 “your organization has disabled claude subscription access” 这类提示，需要联系管理员或者换用个人账号。

Codex CLI 的安装类似，装完后可以用/model命令切换模型，用/compact压缩上下文，用/resume恢复之前的会话。这几个命令是日常高频操作，建议先熟悉。

如果你想让 Claude Code 调用本地模型（比如通过 LM Studio 跑的模型），需要在配置里指定本地 API 地址。这个配置因版本而异，建议参考对应版本的官方文档。第三方 API 接入也是类似思路，关键是找到配置文件里的base_url和api_key字段。

4.2 创建第一个 skill：以“写单元测试”为例

我们从一个最实用的 skill 开始：write-unit-test。这个 skill 的目标是：当项目里新增了业务函数但没有对应测试时，自动生成符合项目规范的单元测试。

先建目录：

mkdir -p skills/write-unit-test/templates

然后创建SKILL.md，内容大致如下：

# write-unit-test ## 触发条件 当新增或修改了 src/ 目录下的业务函数，且 tests/ 目录下没有对应的测试文件时。 ## 前置依赖 - 项目已安装 pytest - tests/ 目录存在 ## 执行步骤 1. 读取被修改的源文件，识别所有公开函数 2. 对每个函数，检查 tests/ 下是否存在同名测试文件 3. 对缺失测试的函数，生成测试用例，覆盖正常输入、边界输入、异常输入 4. 将测试写入 tests/test_<模块名>.py 5. 运行 pytest，确认新测试通过 ## 验证方法 运行 `pytest tests/ -v`，确认新增测试全部通过，且没有破坏已有测试。 ## 注意事项 - 如果函数依赖外部服务，使用 mock 替代真实调用 - 测试命名遵循 test_<函数名>_<场景> 格式 - 断言要具体，避免只断言“不报错”

这个 skill 写完后，放到项目根目录的skills/文件夹里。Claude Code 启动时会自动扫描这个目录，把 skill 加入可用列表。

4.3 配置 agent 自动加载 skill

光有 skill 文件还不够，得让 agent 知道去哪里找。Claude Code 和 Codex CLI 通常支持在项目配置文件里指定 skill 目录。具体配置方式因版本而异，但核心思路是在配置文件里加一段类似这样的内容：

skills: directories: - ./skills auto_load: - write-unit-test - review-code

auto_load里列出的 skill 会在每次启动时自动加载，适合那些高频使用的。其他的按需加载，节省上下文。

配置完后，重启 agent，用/model确认模型正常，然后随便改一个源文件，看 agent 是否会主动调用write-unit-test。如果没反应，检查 skill 的触发条件是不是写得太窄，或者目录路径配错了。

4.4 组合多个 skill 完成复杂任务

单个 skill 跑通后，可以试试组合。比如“给用户模块加一个邮箱验证功能”这个任务，可以拆成：

1. write-code：实现邮箱格式校验函数
2. write-unit-test：为校验函数写测试
3. run-tests：跑测试套件
4. fix-failures：如果有失败，根据错误信息修复
5. update-docs：更新 API 文档

在 agent 里，你可以直接描述任务，让它自己规划 skill 调用顺序。也可以显式指定，比如“先用 write-code 实现，再用 write-unit-test 补测试”。显式指定的好处是可控，适合新手；让 agent 自己规划的好处是灵活，适合熟练之后。

我实测下来，显式指定在任务初期更稳，因为 agent 对项目还不熟，容易规划出奇怪的顺序。等 agent 对项目结构熟悉了，再逐步放手让它自己规划。

4.5 参数计算与选择：skill 粒度的把握

skill 粒度是个需要反复调整的参数。太粗，一个 skill 干太多事，执行不稳定；太细，skill 数量爆炸，agent 选择困难。

我的经验法则是：一个 skill 对应一个可独立验证的产出。比如“写单元测试”的产出是“一组通过的测试”，这个产出可以独立验证，所以适合作为一个 skill。“写代码”的产出是“能运行的代码”，也可以独立验证。但“优化代码”的产出不好验证，就不适合单独成 skill，应该拆成“消除重复代码”“提取常量”等可验证的子技能。

另一个参考维度是执行时间。如果一个 skill 执行超过 5 分钟，说明它可能太粗了，考虑拆分。如果一个 skill 执行不到 10 秒，说明它可能太细了，考虑合并。

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

5.1 skill 不被调用怎么办

这是最常见的问题。agent 明明有这个 skill，但执行任务时就是不调用。排查思路按顺序来：

先检查 skill 的触发条件。把触发条件读一遍，问自己：当前任务真的满足这个条件吗？很多时候是条件写得太窄，比如只写了“新增函数”，但实际任务是“修改函数”，就不匹配。

再检查 skill 目录配置。用 agent 的调试命令（如果有）列出当前加载的 skill，确认目标 skill 在列表里。不在的话，检查配置文件路径。

最后检查 skill 描述文件格式。YAML 对缩进敏感，Markdown 对标题层级敏感。格式错了，agent 可能解析失败但不报错。

5.2 skill 执行结果不稳定

同一个 skill，有时候执行得好，有时候跑偏。这通常是 skill 描述不够具体导致的。

解决办法是把模糊动词换成具体动作。比如“优化代码”换成“删除未使用的导入语句”“把重复的字符串提取为常量”。“检查代码质量”换成“运行ruff check并修复所有警告”。

还有一个技巧是加示例。在 skill 里放一两个输入输出的例子，agent 会参照例子执行，稳定性明显提升。

5.3 上下文被 skill 占满

如果加载了太多 skill，agent 可能没足够上下文理解代码。解决办法前面提过分层加载，这里补充一个：定期清理不用的 skill。项目里总有一些 skill 是特定阶段用的，比如“数据库迁移”只在改 schema 时用。把这些 skill 移到skills/archive/目录，需要时再移回来。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是skill 名用了中文。虽然理论上支持，但 agent 匹配时对中文的处理不如英文稳定。后来全部改成英文动词短语，问题消失。

第二个坑是在 skill 里写了绝对路径。换台机器就失效。后来改成相对路径，配合项目根目录变量，可移植性好很多。

第三个坑是skill 之间循环依赖。A 依赖 B，B 又依赖 A，agent 执行时死循环。后来加了个规则：skill 依赖只能单向，不能成环。

第四个坑是忘了给 skill 加版本号。项目迭代后 skill 内容变了，但 agent 还在用旧版。后来在 skill 文件名里加版本号，比如write-unit-test-v2，切换时明确指定。

6. 进阶玩法：把 superpowers 接入你的日常工作流

6.1 与 VS Code 的配合

Claude Code 有 VS Code 插件，装完后可以在编辑器里直接调用 agent。配合 superpowers，你可以做到：在编辑器里选中一段代码，右键调用review-codeskill，agent 直接在终端里跑审查并给出修改建议。

配置插件时注意一点：插件的 skill 目录可能跟终端版不同。我遇到过终端里能用的 skill，插件里找不到，后来发现是插件有自己的配置路径。解决办法是在插件设置里显式指定 skill 目录，跟终端版保持一致。

6.2 接入第三方模型

如果你想让 superpowers 跑在 DeepSeek、Qwen、GLM 这些模型上，需要用到模型切换工具。核心思路是配置一个兼容层，把不同模型的 API 统一成 Claude Code 或 Codex CLI 能识别的格式。

配置时注意模型的上下文窗口大小。有些模型的窗口比 Claude 小，加载太多 skill 会溢出。这时候要更激进地做分层加载，只保留最核心的 skill。

6.3 团队协作场景

superpowers 在团队里的价值更大。把 skill 目录纳入版本控制，团队成员共享同一套技能定义。新人入职时，不用再口口相传“我们项目的测试规范是什么”，agent 会自动按 skill 执行。

团队协作时建议加一个CONTRIBUTING.md，说明怎么新增 skill、怎么改现有 skill、怎么测试 skill 是否生效。我见过团队因为没人维护 skill，半年后 skill 全部失效，agent 又退化成“裸奔”状态。

6.4 持续迭代：skill 也需要重构

skill 不是写完就完了。项目在变，skill 也要跟着变。我的做法是每个月review一次 skill 目录，做三件事：删掉不再用的，合并重复的，更新过时的。

判断一个 skill 是否过时，看它的验证方法还能不能跑通。如果验证方法失效了，说明 skill 依赖的东西变了，需要更新。如果连续两个月没被调用过，考虑归档。

7. 我个人的使用体会

用 superpowers 这套思路管理 AI 编程助手，最大的感受是从“求着模型干活”变成了“给模型派活”。以前用 Claude Code，经常要反复解释需求，模型还经常理解偏。现在把常见任务都封装成 skill，agent 接到任务后自己匹配、自己执行、自己验证，我只需要在关键节点确认一下。

另一个体会是skill 的质量比数量重要。我一开始贪多，写了二十多个 skill，结果 agent 选择困难，经常调用错的。后来精简到八个核心 skill，每个都打磨得很具体，整体效率反而提升了。

如果你刚开始接触，我的建议是从三个 skill 起步：一个管代码规范，一个管测试，一个管代码审查。这三个覆盖了日常开发的大部分场景，跑顺了再逐步扩展。别一上来就追求大而全，那样只会让自己陷入维护 skill 的泥潭。

最后分享一个小技巧：给每个 skill 加一个“反例”部分，写明什么情况下不该用这个 skill。这能有效减少 agent 的误调用。比如write-unit-test的反例可以写“如果函数只是简单的 getter/setter，不需要单独测试”。加了反例之后，agent 的判断准确率明显提高。