Superpowers 架构：技能发现、加载、遮蔽 3 个机制一次看懂

Superpowers 架构技能发现、加载、遮蔽 3 个机制一次看懂【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是面向编码代理的技能库让代理按方法论执行开发任务。所谓Superpowers 架构核心就是技能系统技能如何被发现、被加载、同名时听谁的。本文基于仓库源码把这三件事拆开讲清。️ 感知层以 SKILL.md 为锚的递归扫描入口函数是findSkillsInDir(dir, sourceType, maxDepth)深度优先遍历目录树默认深度 3 层每个子目录先查有没有SKILL.md有就登记为一个技能单元没有则继续下探。每个技能被记录为四要素路径、技能文件位置、名称、描述外加一个sourceType标记superpowers或personal这是后续命名空间隔离的地基。为什么限 3 层真实仓库里技能只摆两层skills/名字/SKILL.md3 层足以覆盖个人目录的常见摆法又不会在深层树里做无谓递归。四函数契约见 docs/plans/2025-11-22-opencode-support-design.md。 契约层SKILL.md 的 YAML frontmatter 长什么样每个技能文件头部必须有一段 frontmatterextractFrontmatter只关心其中两个字段--- name: brainstorming description: You MUST use this before any creative work... ---名称兜底frontmatter 缺name时直接取目录名保证技能不会因书写疏漏而丢失。描述即触发器description会随find_skills的列表输出展示给代理代理靠它判断该不该调用写法决定命中率。实例见 skills/brainstorming/SKILL.md。 调度层resolveSkillPath 的三步裁决代理要使用某个技能时resolveSkillPath(skillName, superpowersDir, personalDir)接管解析判意图名字带superpowers:前缀置强制官方标记并剥掉前缀查个人未带前缀时先探personalDir/名字/SKILL.md存在即返回兜官方再按同样规则查官方目录都没命中返回 null由调用方提示代理改用find_skills列清单。这套顺序让两级目录无冲突共存调用形式探测顺序结果my-skill无前缀个人 → 官方个人版本遮蔽官方superpowers:brainstorming仅官方显式锁定官方实现两处都不存在—返回 null提示列清单⚖️ 治理层技能遮蔽、共存与更新检查技能遮蔽Shadowing个人技能与官方技能同名时个人版本自动生效。没有配置文件没有注册步骤文件存在本身即声明。无冲突共存不同名的技能互不影响两级目录的清单并排呈现。更新检查checkForUpdates对已安装仓库执行git fetch加状态检查超时 3 秒状态里出现[behind才提示可更新任何网络异常静默返回无更新——绝不阻塞会话启动。上述逻辑在 OpenCode 侧落地于 .opencode/plugins/superpowers.js它内建了自用的 frontmatter 解析并缓存引导内容。 串起来一次会话的完整生命周期会话启动时插件先解析using-superpowers技能作为引导注入代理顺手做更新检查此后代理遇到新增功能类任务brainstorming的描述触发语命中调use_skill路径走完扫描 → 解析 → 裁决 → 读取。若用户本地有同名个人版本注入的就是本地版——个性化就挂在这个点上。引导内容用模块级变量缓存因为会话期间 SKILL.md 不变省掉每步重复读盘。 给技能作者 3 条实操建议目录名即技能名短横线英文与 frontmatter 的name保持一致。description写成触发条件Use when...而非功能摘要——代理靠它决定是否调用。想改官方行为用同名个人技能遮蔽不要 fork 官方目录git pull升级官方后遮蔽依然有效。Superpowers 技能系统本质是目录即注册的小内核扫描负责发现frontmatter 负责声明resolveSkillPath负责裁决。三步看懂你就能预测任何技能在任意环境下的加载结果。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考