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 CLIClaude 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.04Mac 上也没问题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-codeauto_load里列出的 skill 会在每次启动时自动加载适合那些高频使用的。其他的按需加载节省上下文。配置完后重启 agent用/model确认模型正常然后随便改一个源文件看 agent 是否会主动调用write-unit-test。如果没反应检查 skill 的触发条件是不是写得太窄或者目录路径配错了。4.4 组合多个 skill 完成复杂任务单个 skill 跑通后可以试试组合。比如“给用户模块加一个邮箱验证功能”这个任务可以拆成write-code实现邮箱格式校验函数write-unit-test为校验函数写测试run-tests跑测试套件fix-failures如果有失败根据错误信息修复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 占满如果加载了太多 skillagent 可能没足够上下文理解代码。解决办法前面提过分层加载这里补充一个定期清理不用的 skill。项目里总有一些 skill 是特定阶段用的比如“数据库迁移”只在改 schema 时用。把这些 skill 移到skills/archive/目录需要时再移回来。5.4 常见问题速查表问题现象可能原因排查方法解决方式skill 不被调用触发条件太窄读触发条件对比任务放宽条件或加关键词skill 不被调用目录配置错误列出已加载 skill检查配置文件路径执行结果不稳定描述太模糊读执行步骤换成具体动作加示例上下文占满加载太多 skill查看上下文用量分层加载归档低频 skill执行中途失败前置依赖未满足检查依赖声明补依赖检查步骤验证不通过验证方法缺失读 skill 末尾补验证步骤5.5 几个我踩过的坑第一个坑是skill 名用了中文。虽然理论上支持但 agent 匹配时对中文的处理不如英文稳定。后来全部改成英文动词短语问题消失。第二个坑是在 skill 里写了绝对路径。换台机器就失效。后来改成相对路径配合项目根目录变量可移植性好很多。第三个坑是skill 之间循环依赖。A 依赖 BB 又依赖 Aagent 执行时死循环。后来加了个规则skill 依赖只能单向不能成环。第四个坑是忘了给 skill 加版本号。项目迭代后 skill 内容变了但 agent 还在用旧版。后来在 skill 文件名里加版本号比如write-unit-test-v2切换时明确指定。6. 进阶玩法把 superpowers 接入你的日常工作流6.1 与 VS Code 的配合Claude Code 有 VS Code 插件装完后可以在编辑器里直接调用 agent。配合 superpowers你可以做到在编辑器里选中一段代码右键调用review-codeskillagent 直接在终端里跑审查并给出修改建议。配置插件时注意一点插件的 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经常要反复解释需求模型还经常理解偏。现在把常见任务都封装成 skillagent 接到任务后自己匹配、自己执行、自己验证我只需要在关键节点确认一下。另一个体会是skill 的质量比数量重要。我一开始贪多写了二十多个 skill结果 agent 选择困难经常调用错的。后来精简到八个核心 skill每个都打磨得很具体整体效率反而提升了。如果你刚开始接触我的建议是从三个 skill 起步一个管代码规范一个管测试一个管代码审查。这三个覆盖了日常开发的大部分场景跑顺了再逐步扩展。别一上来就追求大而全那样只会让自己陷入维护 skill 的泥潭。最后分享一个小技巧给每个 skill 加一个“反例”部分写明什么情况下不该用这个 skill。这能有效减少 agent 的误调用。比如write-unit-test的反例可以写“如果函数只是简单的 getter/setter不需要单独测试”。加了反例之后agent 的判断准确率明显提高。