8 月 23 日，开源项目 obra/superpowers 以单日 27.6 万星登顶 GitHub Trending——它不是又一个模型或 IDE，而是一套「技能化的 Agent 开发框架」：用 .agents 目录 + SKILL.md + 技能注册表，把「开发方法论」沉淀成 Agent 可消费、可审计的标准库，覆盖需求获取、代码评审、架构决策到部署的完整生命周期。作者 Jesse Vincent（obra）称之为「原始 LLM 能力与生产级交付之间缺失的那一层」。
🦸 本教程适合：想让 Claude Code / Codex / Cursor 里的 Agent 从「即兴发挥」变成「按流程干活」的开发者、技术负责人。我们讲清技能化思维、安装、结构与第一个技能落地。
先搞懂：Superpowers 在解决什么问题
很多人对 AI 编程的抱怨是一致的：「它很聪明，但不可预期」——同一个任务，今天给你惊喜，明天给你惊吓。Superpowers 的思路不是换更聪明的模型，而是给 Agent 上「岗位手册」：把工程师的显性/隐性经验写成一个个技能，每个技能自带提示词模板、校验脚本与反馈闭环。
| 传统用法 | Superpowers 用法 |
|---|---|
| 临时想一句 prompt | 调用沉淀好的技能 |
| Agent 即兴发挥 | Agent 按可审计流程执行 |
| 经验在个人脑子里 | 经验在仓库里可复用 |
| 结果看运气 | 结果可测试、可回归 |
| 换工具就推倒重来 | 技能跨工具通用 |
别误读成「提示词模板合集」：Superpowers 的重点是方法论——每个技能都绑定验证脚本与反馈循环，Agent 执行完能自我检查，而不是写完就交差。
Step 1：安装——把技能装进你的 Agent
1 一套技能，多工具通用
Superpowers 兼容主流 Harness：
1. Claude Code
git clone obra/superpowers
cd superpowers
./install.sh
（或手动把 .agents 目录
拷到工作区根目录）
2. Codex / Cursor / 其他
· 把 skills 目录放进
项目 .agents/skills/
· Agent 启动时自动发现
· 参考《Agent Skills 开放标准》
的目录约定
3. 验证安装
· 对话里问 Agent
「列出你有哪些技能」
· 看到技能清单 = 成功
为什么跨工具：
· 技能 = Markdown + YAML
人类可读，机器可解析
· 不绑定任何厂商运行时💡 想更系统理解「技能为何能跨工具」？建议先看《Agent Plugins 1.0.0 统一打包标准》——插件是「能力包」，技能是「方法论包」，两者互补。
Step 2：拆解一个技能的结构
2 一个技能 = 一份说明书 + 校验逻辑
技能本质是一个文件夹：
.agents/skills/code-review/
├── SKILL.md # 说明书
├── scripts/
│ ├── validate.py # 校验脚本
│ └── check.sh # 检查钩子
└── references/ # 参考材料
SKILL.md 头部（YAML frontmatter）：
---
name: code-review
description: 按团队规范做代码
审查，输出可执行问题清单
trigger: 用户要求审查代码
tags: [review, quality]
---
正文（人类可读的流程）：
1. 读取变更范围
2. 按 checklist 逐项检查
3. 输出：问题/严重级/
建议修复/示例
4. 运行 scripts/validate.py
确认输出格式合规
关键：校验脚本让技能
「可测试」——Agent 跑完
能自己确认做对了description 要写「触发条件」：Agent 靠 description 决定何时调用技能。写得含糊（如「审查」），它可能错过该用的场景；写清楚触发词与输入输出，命中率才高。
Step 3：技能注册表与依赖管理
3 技能多了，怎么管
Superpowers 提供轻量治理机制：
1. 技能注册表（registry）
· 一个索引文件登记
全部技能与版本
· Agent 启动时读取
· 新技能 = 登记 + 放目录
2. 依赖管理
· 技能可以依赖其他技能
（如「发布」依赖
「测试」与「评审」）
· 声明式依赖，Agent
自动按序执行
3. 版本与变更
· 技能改动走 git
· 校验脚本保证
「改了不坏」
典型仓库结构：
.agents/
├── config.yaml # 全局配置
├── registry.yaml # 技能注册表
├── skills/ # 技能库
│ ├── code-review/
│ ├── architecture/
│ └── deployment/
└── workflows/ # 组合流程💡 这套「技能资产化」思路与《SkillHub 技能资产化》同频：先把自己团队的技能沉淀成资产，再谈跨团队复用与沉淀。
Step 4：跑通一个完整开发生命周期
4 需求 → 评审 → 部署，全程可审计
Superpowers 覆盖完整生命周期，
以一个功能开发为例：
1. 需求获取（elicitation）
· 技能引导提问
· 产出明确需求文档
· 带验收标准
2. 架构决策（ADR）
· 技能模板记录决策
背景/选项/理由
· 决策可追溯
3. 编码与自测
· 每个任务绑定校验脚本
· Agent 交付前自检
4. 代码评审
· 技能按团队 checklist 审查
· 输出结构化问题单
5. 部署与验证
· 发布技能 + 回滚预案
· 上线后回归
与普通用法对比：
· 普通：Agent「自由发挥」
· Superpowers：Agent
「按 SOP 执行」
· 产出质量从「看运气」
变成「看流程」别一次上全流程：先挑 1-2 个最痛环节（比如代码评审 + 架构决策）技能化，跑顺了再扩。全流程一步到位最容易翻车。
Step 5：用「测试 harness」验证技能行为
5 技能也能被测试、被回归
Superpowers 内置技能测试思路：
1. 写样例输入
· 每个技能配 3-5 个
典型输入（含边界）
2. 定义期望输出
· 结构、关键字段、红线
3. 跑测试
· 让 Agent 执行技能
· 校验脚本比对输出
· 不达标 = 技能需修
4. 持续回归
· 技能改动后全量跑
· 防止「修 A 技能
坏了 B 技能」
这与《Agent 评测 Evals》
一脉相承：
· 评测的是「技能」这一层
· 比裸模型评测更贴近
真实使用场景
收益：
· 技能质量可度量
· 换模型不换技能，
行为仍稳定
· 新人接手有据可依💡 配合《吴恩达六大子技能》里的「评估驱动开发」食用更佳：技能库就是你的「评估集」之一，改动必回归。
Step 6：团队落地建议
6 从个人玩具到团队基础设施
落地四步：
第一步：个人试点
· 装进自己的 Claude Code
· 挑 1 个技能跑两周
第二步：团队评审
· 把试点成果给团队看
· 收集「缺什么技能」
· 确立技能命名规范
第三步：仓库沉淀
· 技能库随代码仓库管理
· 合并前必须过校验
· 技能改动走 PR + 评审
第四步：融入流程
· CI 里跑技能测试
· 新成员 onboarding
从读技能库开始
· 季度盘点：哪些技能
该升级/废弃
判断标准：
· 换人换工具，流程不塌
· 产出可审计、可回滚
· 新人能看懂「为什么
这么做」
与《Record a Skill 录屏蒸馏》
结合：高手操作录屏 →
自动生成技能初稿 →
再按规范打磨入库最怕「技能僵尸」：没人维护的技能会悄悄过时，Agent 还在照本宣科。建议给技能库加「最后验证日期」，超过 90 天没跑的技能标记为待复核。
常见问题速查
| 你遇到的现象 | 大概率原因 & 解决 |
|---|---|
| Agent 不调用技能 | description 触发词不明确：写明触发条件与输入输出 |
| 技能结果不稳定 | 缺校验脚本：给技能加 validate 步骤，让 Agent 自检 |
| 技能库越来越大 | 该治理了：注册表 + 版本管理 + 季度盘点废弃技能 |
| 和现有插件/标准冲突 | 技能（方法论）与插件（能力包）互补：插件给工具，技能给流程 |
| 换工具后技能失效 | 检查是否用了厂商私有字段：保持纯 Markdown+YAML，跨工具通用 |