Superpowers 技能发现与加载机制深度解析：从 bootstrap 注入到技能遮蔽

Superpowers 技能发现与加载机制深度解析：从 bootstrap 注入到技能遮蔽

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers 是一套给编码 Agent 用的零依赖技能框架，把软件开发方法论拆成一个个可组合的技能目录。它要解决的真实问题很具体：技能文件躺在磁盘上时是"死"的，Agent 不会主动去看。本文沿一次会话的时间线，拆解技能发现、SKILL.md 加载与优先级遮蔽的完整机制。

🪝 一、先问一个反直觉的问题：谁来调用这些技能？

假设你的 Agent 工作区里有十几个技能目录，每个目录一份 SKILL.md。问题是：默认情况下，模型并不知道这些文件存在，更不会在动手前想起去读。官方移植文档里把这叫作最典型的失败形态——"present on disk, never invoked"（存在于磁盘，从未被调用）。

Superpowers 的答案分三幕，串起来就是一条完整的技能生命周期：

1. 启动注入：会话一开场，把"总纲技能"的内容直接塞进模型上下文，告诉它"技能存在，且你必须先查再用"；
2. 按需发现：模型判断某任务可能适用某个技能时，通过目录扫描 + SKILL.md 解析找到它并读取触发条件；
3. 路径解析：把技能名解析成真实文件路径，并按"个人版本遮蔽官方版本"的规则决定加载哪一份。

下面逐幕展开：它做什么、怎么做、以及为什么这样设计。

📡 二、会话启动的第一秒：bootstrap 注入怎么发生

它做什么：在用户发出第一条消息之前，using-superpowers这份"总纲"必须已经出现在模型视野里。它是所有自动触发行为的入口，没有它，其余技能全部失效。

怎么做：机制挂在会话钩子上。hooks/hooks.json把SessionStart事件（匹配startup|clear|compact三种时机）映射到一个 bash 脚本，脚本读取skills/using-superpowers/SKILL.md全文，包进<EXTREMELY_IMPORTANT>标签后以 JSON 输出：

{ "hooks": { "SessionStart": [ { "matcher": "startup|clear|compact", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start" }] } ] } }

细节上有个容易忽视的点：不同宿主平台对注入字段的要求并不一致——Cursor 期望additional_context，Claude Code 期望嵌套在hookSpecificOutput下的additionalContext，Copilot CLI 则用顶层additionalContext。hooks/session-start脚本会依据环境变量只输出当前平台消费的那一个字段，避免同一内容被重复注入两次。

为什么这样设计：与其指望模型"自觉"去翻目录，不如在会话起点强制建立规则意识。总纲里那句"If you think there is even a 1% chance a skill might apply"就是靠这一步注入生效的。这也是跨平台移植的核心不变量：技能内容处处相同，变的只是这一层注入器。

🔍 三、按需发现：SKILL.md 就是技能的"户口"

它做什么：当模型判断任务可能适用某技能时，系统需要回答两个问题——哪些目录算技能？每个技能的触发条件是什么？

怎么做：发现逻辑是纯目录约定驱动，共享核心模块的接口在docs/plans/2025-11-22-opencode-support-design.md中定义为三个函数：

• findSkillsInDir(dir, maxDepth)：递归扫描目录，默认最大深度 3 层；目录里存在SKILL.md即判定为技能目录；
• extractFrontmatter(filePath)：解析技能文件头部的 YAML 元数据，取出name与description；
• 命名空间隔离：个人技能与官方（superpowers）技能分目录存放，互不污染。

一份典型的元数据长这样：

--- name: brainstorming description: "You MUST use this before any creative work - creating features, building components..." ---

注意description的写法：它不是在描述"这个技能是干什么的"，而是在陈述何时必须使用它。这句话会直接进入模型的决策依据，所以措辞本身就是一种行为约束。

为什么这样设计：这里有一个刻意的取舍——不做集中式注册表。没有skills.json、没有配置文件需要手工维护，"目录里放一份 SKILL.md"本身就是声明。新增技能零配置，删除技能零善后。代价是拼错目录名要到运行期才会暴露（后文取舍一节展开）。

深度上限取 3 是一个性能与覆盖面的平衡：足够容纳skills/<name>/及其嵌套的scripts/、references/子目录，又不会让扫描失控到全盘遍历。

🎭 四、加载与遮蔽：一个技能名如何找到真实文件

它做什么：用户或模型给出一个技能名（可能是brainstorming，也可能是superpowers:brainstorming），系统要把它解析成磁盘上的具体路径。

怎么做：resolveSkillPath(skillName, dirs)按三条规则执行，优先级从高到低：

1. 显式前缀：带superpowers:前缀时，强制命中官方版本，跳过一切遮蔽判断；
2. 个人遮蔽：无显式前缀时，若个人技能目录存在同名技能，加载个人版本——官方版本被"遮蔽"（shadow）；
3. 回退：个人目录没有同名技能时，自动回退到官方实现。

为什么这样设计：遮蔽而不是报错，是为了支持一种非常实用的工作流——把官方技能复制一份到个人目录，从"最小改动"开始逐步定制，官方升级不影响你的副本，你随时可以删掉副本恢复原状。整个过程无冲突、无迁移、无锁定，优先级规则是确定性的。配合 Git 仓库形式的更新检查，技能库本身也保持可升级状态。

⚖️ 五、取舍清单：它放弃了什么，为什么值得

这一节是理解这套架构的关键——它的好用，都来自一些明确的"不做"：

• 没有注册表，没有编译期校验。目录约定即契约，拼写错误、层级放错要到运行期才发现。换来的是新增/删除技能零配置，以及技能库与宿主解耦。
• 没有冲突检测。同名技能不会报错，而是被静默遮蔽。这要求使用者（和排障者）清楚优先级规则；作为交换，它天然支持渐进式定制。
• 技能正文被视为"行为代码"而非文档。项目明确拒绝"为了符合某套写作规范"而改写技能内容，改动必须附带前后对比的评测证据。这提高了修改门槛，但保证了经过调校的措辞（比如那些反推诿的 Red Flags 表格）不会被随意稀释。
• 零依赖是硬约束。核心不引入第三方依赖；需要外部工具的扩展，被要求拆成独立插件。

这些放弃换来的回报是：同一套技能内容可以原样跑在 Claude Code、Codex、Gemini CLI、pi 等多个宿主上，移植新宿主时只需要写一个 bootstrap 注入器和一份工具名映射，从不触碰skills/*/SKILL.md正文。

🛠️ 六、实战：两个触发场景与三个常见坑

场景一：头脑风暴的自动触发。用户说"let's make a react todo list"，总纲规则要求 Agent 在回应（包括澄清问题）之前先检查技能，于是brainstorming被触发。该技能内部有一道 HARD-GATE：设计稿未经用户批准前，禁止写任何实现代码、禁止搭脚手架——哪怕"只是一个 todo 列表"。这正是"技能先于响应"规则在真实会话里的样子。

场景二：子代理驱动开发。计划被拆成独立任务后，subagent-driven-development技能让每个任务由独立子代理执行，配合评审提示词（task-reviewer-prompt.md、re-review-prompt.md）做两阶段把关，这是"技能组合出工作流"的典型样例。

三个坑：

1. 只拷技能、不注 bootstrap。把skills/目录复制进项目但宿主没有会话启动注入，技能就永远只是死文件。官方给出的验收测试很直接：在干净会话里发送 "Let's make a react todo list"，看brainstorming是否自动触发——不触发就不算集成成功。
2. 在技能正文里写死工具名。技能应只描述动作（"派发子代理""读取文件"），具体工具名翻译放在按宿主拆分的references/<harness>-tools.md里。正文一旦绑定工具名，跨宿主可移植性立即归零。
3. 以"只是简单问题"为由跳过技能检查。总纲里的 Red Flags 表格逐条列出这类自我合理化话术，本质是把"什么时候该停"也写成了可加载的规则。

本地体验完整流程可以克隆仓库查看：

git clone https://gitcode.com/GitHub_Trending/su/superpowers

📌 七、一句话总结与延伸路径

Superpowers 的核心价值，在于把"开发纪律"变成了可加载、可测试、可遮蔽的文件系统：启动注入负责建立规则意识，SKILL.md 约定负责发现，遮蔽机制负责定制，三者都不依赖任何中央配置。

延伸阅读（仓库内路径）：

• 总纲技能全文：skills/using-superpowers/SKILL.md（含技能优先级与 Red Flags 表格）
• 跨宿主移植指南：docs/porting-to-a-new-harness.md（明确 bootstrap 是"整个集成的全部"）
• 钩子实现：hooks/session-start（多平台字段分支逻辑）
• 基础设施测试：tests/目录（钩子、插件清单、生命周期等用例）

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers