Superpowers 源码解读（一）：核心架构理解

从零开始深入理解 Claude Code 技能系统的设计哲学

前言

Superpowers 是一套为 Claude Code 设计的技能系统，通过 Hook 机制和精心设计的技能定义，让 AI 助手能够更智能地辅助开发工作。作为一个 Java 开发者，我决定深入学习这套系统的源码，理解其设计思想。

本系列第一篇，先从整体架构入手。

📁 本文学习目录

bash 复制代码

.claude-plugin/          # 插件配置
├── plugin.json          # 插件元数据
└── marketplace.json     # 市场配置

hooks/                   # 会话钩子
├── hooks.json          # Hook 触发配置
└── session-start       # 会话启动脚本

skills/using-superpowers/
└── SKILL.md            # 入口技能

项目结构概览

bash 复制代码

superpowers/
├── .claude-plugin/          # 插件配置
├── skills/                  # 核心技能定义（14个技能）
├── hooks/                   # 会话钩子
├── agents/                  # 子代理定义
├── tests/                   # 测试用例
├── docs/                    # 文档
└── commands/                # 已废弃的命令

一、插件配置

1.1 plugin.json - 插件元数据

json 复制代码

{
  "name": "superpowers",
  "description": "...",
  "version": "5.0.5"
}

关键字段：

name : 技能命名空间前缀，如 superpowers:brainstorming
description: 影响搜索和发现
version: 当前版本 5.0.5

1.2 marketplace.json - 市场配置

定义插件列表和版本，source: "./" 指向插件根目录。

二、Hook 系统

Hook 系统是 superpowers 的"注入点"，在关键时刻自动注入上下文。

2.1 触发条件

在 hooks/hooks.json 中定义：

触发器	说明
`startup`	新会话启动
`clear`	清除对话
`compact`	压缩对话历史

2.2 Hook 系统工作流程

flowchart TD subgraph 触发层["触发层"] A1[会话启动 startup] A2[清除对话 clear] A3[压缩历史 compact] end subgraph 执行层["执行层"] B[读取 hooks.json] C[匹配触发条件] D[执行 run-hook.cmd] end subgraph 脚本层["脚本层"] E{检测平台} E1[Windows: 调用 Git Bash] E2[Unix: 直接执行 bash] F[运行 session-start] end subgraph 注入层["注入层"] G[检测旧版目录] H[读取 using-superpowers/SKILL.md] I[JSON 转义处理] J{判断平台} J1[Cursor: additional_context] J2[Claude Code: hookSpecificOutput] end A1 --> B A2 --> B A3 --> B B --> C --> D D --> E E --> E1 --> F E --> E2 --> F F --> G --> H --> I --> J J --> J1 J --> J2

2.3 跨平台执行器

run-hook.cmd 实现了跨平台支持：

Windows: 找 Git Bash 执行
Unix: 直接执行 bash
文件扩展名无 .sh，避免 Windows 自动加 bash 前缀

三、技能发现机制

这是 superpowers 最核心的设计之一。

3.1 技能发现完整流程

flowchart TD subgraph 用户交互["用户交互"] A[用户发送消息] end subgraph 技能匹配["技能匹配"] B[Claude 分析消息意图] C{是否有技能适用?} C1[无: 继续默认行为] C2[有: 哪怕只有 1% 可能性] end subgraph 技能加载["技能加载"] D[调用 Skill 工具] E[宣布使用技能] F[读取 SKILL.md] G[解析技能定义] end subgraph 优先级判断["优先级判断"] H{检查优先级} H1[用户指令: 最高优先] H2[Superpowers 技能: 次优先] H3[系统默认: 最低优先] end subgraph 执行阶段["执行阶段"] I[检查技能类型] J{Rigid 还是 Flexible?} J1[Rigid: 严格遵循流程] J2[Flexible: 根据上下文调整] K[检查 Red Flags] L[执行技能工作流] end subgraph 结果输出["结果输出"] M[输出结果] N[记录执行日志] end A --> B --> C C --> C1 C --> C2 --> D D --> E --> F --> G G --> H H --> H1 H --> H2 H --> H3 H1 & H2 & H3 --> I --> J J --> J1 --> K J --> J2 --> K K --> L --> M --> N

3.2 关键设计

1. 强制优先级

flowchart LR A[用户指令] -->|最高| B[执行] C[Superpowers 技能] -->|次高| B D[系统默认] -->|最低| B style A fill:#ff6b6b style C fill:#ffd93d style D fill:#6bcb77

2. Red Flags 表

列出所有"自我合理化"借口，防止 AI 偷懒跳过技能。

3. 技能类型

类型	说明
Rigid（严格）	必须精确遵循，如 TDD
Flexible（灵活）	可根据上下文调整

4. CSO（Claude Search Optimization）

description 字段只描述触发条件，不描述工作流。这和传统的 SEO 不同------不是堆砌关键词，而是精确描述"什么情况下应该使用这个技能"。

四、完整启动流程

4.1 Claude Code 启动到技能执行

sequenceDiagram participant U as 用户 participant CC as Claude Code participant P as plugin.json participant H as Hook 系统 participant S as session-start participant US as using-superpowers participant SK as Skill 工具 U->>CC: 启动 Claude Code CC->>P: 加载插件元数据 P-->>CC: 返回插件配置 Note over CC,H: SessionStart Hook 触发 CC->>H: 触发 startup 事件 H->>S: 执行 session-start 脚本 S->>S: 检测旧版目录 S->>US: 读取 SKILL.md S->>S: JSON 转义处理 S-->>H: 返回注入内容 H-->>CC: 注入 using-superpowers Note over CC: Claude 就绪 U->>CC: 发送消息 CC->>CC: 分析消息意图 CC->>SK: 调用匹配的技能 SK->>SK: 加载技能定义 SK-->>CC: 执行技能工作流 CC-->>U: 返回结果

4.2 核心洞察

Hook 系统是"注入点"，using-superpowers 是"入口技能"，所有其他技能通过 Skill 工具按需加载。

这种设计实现了懒加载------只有在需要时才加载具体技能，避免了上下文膨胀。

4.3 架构分层图

graph TB subgraph 表现层["表现层"] A[用户交互] B[Claude Code CLI] end subgraph 注入层["注入层"] C[Hook 系统] D[session-start] end subgraph 入口层["入口层"] E[using-superpowers<br/>入口技能] end subgraph 技能层["技能层"] F[TDD] G[Debugging] H[Brainstorming] I[Writing Plans] J[...其他技能] end subgraph 代理层["代理层"] K[code-reviewer] L[implementer] M[spec-reviewer] end A --> B B --> C C --> D D --> E E --> F & G & H & I & J F & G --> K & L & M

五、总结

第一阶段学习，我理解了 superpowers 的整体架构：

组件	作用
plugin.json	定义插件元数据和命名空间
Hook 系统	在会话启动时自动注入入口技能
using-superpowers	入口技能，引导其他技能的加载
CSO	优化技能发现的关键设计

下一阶段，将深入学习技能系统设计 ，包括 SKILL.md 结构、流程图设计、CSO 优化策略等。

参考资料

Superpowers 源码：github.com/obra/superp...
作者博客：blog.fsck.com/2025/10/09/...
Discord 社区：discord.gg/Jd8Vphy9jq

本文是 Superpowers 源码学习系列的第一篇，后续会继续分享学习心得。欢迎关注！