Superpowers 技能发现与加载机制深度解析从 bootstrap 注入到技能遮蔽【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一套给编码 Agent 用的零依赖技能框架把软件开发方法论拆成一个个可组合的技能目录。它要解决的真实问题很具体技能文件躺在磁盘上时是死的Agent 不会主动去看。本文沿一次会话的时间线拆解技能发现、SKILL.md 加载与优先级遮蔽的完整机制。 一、先问一个反直觉的问题谁来调用这些技能假设你的 Agent 工作区里有十几个技能目录每个目录一份 SKILL.md。问题是默认情况下模型并不知道这些文件存在更不会在动手前想起去读。官方移植文档里把这叫作最典型的失败形态——present on disk, never invoked存在于磁盘从未被调用。Superpowers 的答案分三幕串起来就是一条完整的技能生命周期启动注入会话一开场把总纲技能的内容直接塞进模型上下文告诉它技能存在且你必须先查再用按需发现模型判断某任务可能适用某个技能时通过目录扫描 SKILL.md 解析找到它并读取触发条件路径解析把技能名解析成真实文件路径并按个人版本遮蔽官方版本的规则决定加载哪一份。下面逐幕展开它做什么、怎么做、以及为什么这样设计。 二、会话启动的第一秒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_contextClaude Code 期望嵌套在hookSpecificOutput下的additionalContextCopilot 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)按三条规则执行优先级从高到低显式前缀带superpowers:前缀时强制命中官方版本跳过一切遮蔽判断个人遮蔽无显式前缀时若个人技能目录存在同名技能加载个人版本——官方版本被遮蔽shadow回退个人目录没有同名技能时自动回退到官方实现。为什么这样设计遮蔽而不是报错是为了支持一种非常实用的工作流——把官方技能复制一份到个人目录从最小改动开始逐步定制官方升级不影响你的副本你随时可以删掉副本恢复原状。整个过程无冲突、无迁移、无锁定优先级规则是确定性的。配合 Git 仓库形式的更新检查技能库本身也保持可升级状态。⚖️ 五、取舍清单它放弃了什么为什么值得这一节是理解这套架构的关键——它的好用都来自一些明确的不做没有注册表没有编译期校验。目录约定即契约拼写错误、层级放错要到运行期才发现。换来的是新增/删除技能零配置以及技能库与宿主解耦。没有冲突检测。同名技能不会报错而是被静默遮蔽。这要求使用者和排障者清楚优先级规则作为交换它天然支持渐进式定制。技能正文被视为行为代码而非文档。项目明确拒绝为了符合某套写作规范而改写技能内容改动必须附带前后对比的评测证据。这提高了修改门槛但保证了经过调校的措辞比如那些反推诿的 Red Flags 表格不会被随意稀释。零依赖是硬约束。核心不引入第三方依赖需要外部工具的扩展被要求拆成独立插件。这些放弃换来的回报是同一套技能内容可以原样跑在 Claude Code、Codex、Gemini CLI、pi 等多个宿主上移植新宿主时只需要写一个 bootstrap 注入器和一份工具名映射从不触碰skills/*/SKILL.md正文。️ 六、实战两个触发场景与三个常见坑场景一头脑风暴的自动触发。用户说lets make a react todo list总纲规则要求 Agent 在回应包括澄清问题之前先检查技能于是brainstorming被触发。该技能内部有一道 HARD-GATE设计稿未经用户批准前禁止写任何实现代码、禁止搭脚手架——哪怕只是一个 todo 列表。这正是技能先于响应规则在真实会话里的样子。场景二子代理驱动开发。计划被拆成独立任务后subagent-driven-development技能让每个任务由独立子代理执行配合评审提示词task-reviewer-prompt.md、re-review-prompt.md做两阶段把关这是技能组合出工作流的典型样例。三个坑只拷技能、不注 bootstrap。把skills/目录复制进项目但宿主没有会话启动注入技能就永远只是死文件。官方给出的验收测试很直接在干净会话里发送 Lets make a react todo list看brainstorming是否自动触发——不触发就不算集成成功。在技能正文里写死工具名。技能应只描述动作派发子代理读取文件具体工具名翻译放在按宿主拆分的references/harness-tools.md里。正文一旦绑定工具名跨宿主可移植性立即归零。以只是简单问题为由跳过技能检查。总纲里的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Superpowers 技能发现与加载机制深度解析：从 bootstrap 注入到技能遮蔽
Superpowers 技能发现与加载机制深度解析从 bootstrap 注入到技能遮蔽【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一套给编码 Agent 用的零依赖技能框架把软件开发方法论拆成一个个可组合的技能目录。它要解决的真实问题很具体技能文件躺在磁盘上时是死的Agent 不会主动去看。本文沿一次会话的时间线拆解技能发现、SKILL.md 加载与优先级遮蔽的完整机制。 一、先问一个反直觉的问题谁来调用这些技能假设你的 Agent 工作区里有十几个技能目录每个目录一份 SKILL.md。问题是默认情况下模型并不知道这些文件存在更不会在动手前想起去读。官方移植文档里把这叫作最典型的失败形态——present on disk, never invoked存在于磁盘从未被调用。Superpowers 的答案分三幕串起来就是一条完整的技能生命周期启动注入会话一开场把总纲技能的内容直接塞进模型上下文告诉它技能存在且你必须先查再用按需发现模型判断某任务可能适用某个技能时通过目录扫描 SKILL.md 解析找到它并读取触发条件路径解析把技能名解析成真实文件路径并按个人版本遮蔽官方版本的规则决定加载哪一份。下面逐幕展开它做什么、怎么做、以及为什么这样设计。 二、会话启动的第一秒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_contextClaude Code 期望嵌套在hookSpecificOutput下的additionalContextCopilot 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)按三条规则执行优先级从高到低显式前缀带superpowers:前缀时强制命中官方版本跳过一切遮蔽判断个人遮蔽无显式前缀时若个人技能目录存在同名技能加载个人版本——官方版本被遮蔽shadow回退个人目录没有同名技能时自动回退到官方实现。为什么这样设计遮蔽而不是报错是为了支持一种非常实用的工作流——把官方技能复制一份到个人目录从最小改动开始逐步定制官方升级不影响你的副本你随时可以删掉副本恢复原状。整个过程无冲突、无迁移、无锁定优先级规则是确定性的。配合 Git 仓库形式的更新检查技能库本身也保持可升级状态。⚖️ 五、取舍清单它放弃了什么为什么值得这一节是理解这套架构的关键——它的好用都来自一些明确的不做没有注册表没有编译期校验。目录约定即契约拼写错误、层级放错要到运行期才发现。换来的是新增/删除技能零配置以及技能库与宿主解耦。没有冲突检测。同名技能不会报错而是被静默遮蔽。这要求使用者和排障者清楚优先级规则作为交换它天然支持渐进式定制。技能正文被视为行为代码而非文档。项目明确拒绝为了符合某套写作规范而改写技能内容改动必须附带前后对比的评测证据。这提高了修改门槛但保证了经过调校的措辞比如那些反推诿的 Red Flags 表格不会被随意稀释。零依赖是硬约束。核心不引入第三方依赖需要外部工具的扩展被要求拆成独立插件。这些放弃换来的回报是同一套技能内容可以原样跑在 Claude Code、Codex、Gemini CLI、pi 等多个宿主上移植新宿主时只需要写一个 bootstrap 注入器和一份工具名映射从不触碰skills/*/SKILL.md正文。️ 六、实战两个触发场景与三个常见坑场景一头脑风暴的自动触发。用户说lets make a react todo list总纲规则要求 Agent 在回应包括澄清问题之前先检查技能于是brainstorming被触发。该技能内部有一道 HARD-GATE设计稿未经用户批准前禁止写任何实现代码、禁止搭脚手架——哪怕只是一个 todo 列表。这正是技能先于响应规则在真实会话里的样子。场景二子代理驱动开发。计划被拆成独立任务后subagent-driven-development技能让每个任务由独立子代理执行配合评审提示词task-reviewer-prompt.md、re-review-prompt.md做两阶段把关这是技能组合出工作流的典型样例。三个坑只拷技能、不注 bootstrap。把skills/目录复制进项目但宿主没有会话启动注入技能就永远只是死文件。官方给出的验收测试很直接在干净会话里发送 Lets make a react todo list看brainstorming是否自动触发——不触发就不算集成成功。在技能正文里写死工具名。技能应只描述动作派发子代理读取文件具体工具名翻译放在按宿主拆分的references/harness-tools.md里。正文一旦绑定工具名跨宿主可移植性立即归零。以只是简单问题为由跳过技能检查。总纲里的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考