Superpowers 平台中立配置文件引用设计多 Agent 运行时下「instructions file」的替换规则与落地验证【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 插件需要同时运行在 Claude Code、Codex、Gemini CLI、OpenCode 等多个 Agent 运行时上不同运行时各自读取不同的指令文件CLAUDE.md、AGENTS.md、GEMINI.md。本文基于仓库中的设计文档 2026-05-05-platform-neutral-config-refs-design.md下称 Phase B spec完整讲解这一「平台中立配置文件引用」改造的背景、替换规则、提交与验证计划并结合当前仓库源码核实每一条规则的落地结果帮助读者掌握在多平台技能库中消除单平台假设的工程方法。背景从 Phase A 到 Phase B 的平台中立化分阶段推进Superpowers 的插件内容最初面向 Claude Code 编写随后被分发到多个 Agent 运行时。Phase A见 2026-05-05-platform-neutral-prose-design.md解决的是泛化的第三人称 “Claude” 措辞问题——把泛指「某个 agent」的句子改写为 your agent / the agent 等中性表达但明确把「配置文件引用」CLAUDE.md、AGENTS.md、GEMINI.md 的优先级列表与项目约定存放位置的提示划为 Phase B 的范围。Phase B 要处理的就是 Phase A 留下的下一类问题技能文件里把平台专属的指令文件当作唯一存在的写法。按 spec 的表述插件运行在多个 harness 上每个 harness 读取各自的指令文件当一个 skill 以「CLAUDE.md 是唯一文件」的姿态提及时这是一种 Claude-Code-centric 的假设在 Codex / Gemini CLI / OpenCode 上不成立。整个平台中立化工作按「引用类别」拆分成多个 phasePhase A 泛化措辞、Phase B 配置文件引用、Phase C 营销文案、Phase D 平台工具引用、Phase E 工具名引用每个 phase 独立成文、独立提交这是本文方法可以借鉴的关键点一次只处理一类引用规则边界清晰便于验证和回退。范围界定只改两处「活跃技能」中的 CLAUDE.md 引用spec 对 In scope 的定义非常克制——只针对活跃技能active skills中的两行具体文字skills/writing-skills/SKILL.md第 58 行——Project-specific conventions (put in CLAUDE.md)skills/receiving-code-review/SKILL.md第 30 行——Youre absolutely right! (explicit CLAUDE.md violation)而 Out of scope 部分逐一排除了容易被误伤的目标每一条都给出了不改的理由skills/using-superpowers/SKILL.md的用户指令优先级列表——该列表已经包容性地列出了全部三个文件名CLAUDE.md、GEMINI.md、AGENTS.md这是多平台插件对「什么才算用户指令」的真实主张本身正确无需修改。当前仓库中这条位于 using-superpowers/SKILL.mdUser instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior.历史 / 示例工件CREATION-LOG.md 中的归属路径~/.claude/CLAUDE.md是历史事实改写等于改写历史与 Phase A 对历史工件的处理原则一致CLAUDE_MD_TESTING.md 整个文件就是测试 CLAUDE.md 内容变体的完整示例文件名、正文以及 testing-skills-with-subagents.md 对它的引用都保持原样——「规范化它们反而会毁掉这个示例」。平台工具引用Gemini CLI 工具映射中提及 GEMINI.md 的内容——归入 Phase D 候选不在本阶段处理。这种「白名单式」的范围界定配合后文的 grep 验证构成了 spec 可执行性的核心。替换规则两条规则各对应一处修改spec 为两处修改各给出一条独立规则并解释了为什么选这个措辞而不是另一个候选词。规则 1「项目特定约定该放哪里」→ 使用通用短语针对writing-skills/SKILL.md:58Before:Project-specific conventions (put in CLAUDE.md)After:Project-specific conventions (put in your instructions file)spec 给出的决策依据是用通用短语而不是挑选某一个文件名。不同 harness 读取不同文件CLAUDE.md、AGENTS.md、GEMINI.md 等技能不应假设其中任何一个而「每个平台的首选文件名」应该由平台工具参考文档references/{codex,copilot,gemini}-tools.md一类文件来承载——即技能正文保持中立平台差异下沉到 per-platform 参考文档。当前仓库中该规则已落地writing-skills/SKILL.md 第 58 行的现文为- Project-specific conventions (put in your instructions file)它位于 Dont create for 列表中与「一次性方案」「别处已有充分文档的标准实践」并列——这条规则同时回答了「技能与用户指令文件的内容边界如何划分」项目特定约定不属于可复用技能应写入用户自己的 instructions file。规则 2「(explicit CLAUDE.md violation)」括注 → 「instruction-file violation」针对receiving-code-review/SKILL.md:30Before:Youre absolutely right! (explicit CLAUDE.md violation)After:Youre absolutely right! (explicit instruction-file violation)这条规则的微妙之处在于括注本身在做实事它告诉读者这句话不只是风格不好而是主动违反了大量用户写入指令文件的规则。spec 选择 instruction file 作为跨平台统称同时覆盖 AGENTS.md / CLAUDE.md / GEMINI.md理由是它既保留了原有信号强度又没有选定某个具体文件名也没有软化成 common 之类的模糊表述。当前仓库中 receiving-code-review/SKILL.md 第 30 行的现文为- Youre absolutely right! (explicit instruction-file violation)该行位于 Forbidden Responses 章节属于接收 code review 反馈时「绝不使用」的开场白清单之一与 Great point!表演性附和、Let me implement that now未验证就动手并列替换后的括注使这条禁令在所有平台上语义一致。参考文档承载平台差异的分工「技能正文中立 平台参考文档解析」这一分工在仓库中有实际体现。using-superpowers/SKILL.md 的 Platform Adaptation 章节按 harness 分派阅读- Codex: references/codex-tools.md - Pi: references/pi-tools.md - Antigravity: references/antigravity-tools.md其中 gemini-tools.md 第 24 行明确给出了 your instructions file 的平台解析When a skill mentions your instructions file, on Gemini CLI this isGEMINI.md. Gemini CLI loadsGEMINI.mdhierarchically: global at~/.gemini/GEMINI.md, project-level files in workspace directories and their ancestors, and sub-directoryGEMINI.mdfiles when a tool accesses files in those directories.这正好印证了规则 1 的设计意图读者在 Gemini CLI 上读到 your instructions file 时可以通过平台参考文档把它解析为真实文件名及其层级加载规则。提交计划与验证方案原子提交 grep 兜底提交计划spec 规划了三个按顺序执行的原子提交每个提交信息标注 Phase B 和切片名使提交序列自文档化writing-skills/SKILL.md——项目约定存放位置一行的 CLAUDE.md → your instructions filereceiving-code-review/SKILL.md——违规括注中的 CLAUDE.md → instruction-file平台工具参考文档——为每个references/{codex,copilot,gemini}-tools.md补上该平台的首选指令文件名CLAUDE.md、AGENTS.md、GEMINI.md 等使读者能把 your instructions file 解析为真实文件名。验证方法验证分为两个粒度全部基于阅读与 grep无测试代码每个提交后通读改动段落确认语法与语义仍然通顺grep -n CLAUDE\.md touched-file——活跃正文中不应再有残留命中已记录的 carve-out 除外。全部提交后grep -rn CLAUDE\.md skills/的返回结果应只剩已记录的例外集合CREATION-LOG、CLAUDE_MD_TESTING 及其入站引用、using-superpowers 中的优先级列表。这套验证方式可以直接在仓库中复核。对当前skills/目录执行等价的CLAUDE\.md检索命中恰好是且仅是 spec 预期的那几类例外systematic-debugging/CREATION-LOG.md——历史归属路径~/.claude/CLAUDE.mdusing-superpowers/SKILL.md——用户指令优先级列表writing-skills/testing-skills-with-subagents.md——指向示例的入站引用writing-skills/examples/CLAUDE_MD_TESTING.md——示例文件本身。也就是说活跃技能正文中已无裸 CLAUDE.md 引用验证结论与 spec 的预期完全一致。Non-goals明确「不做什么」spec 用三条非目标锁住了改动边界不调整using-superpowers/SKILL.md中优先级列表的顺序——CLAUDE.md / GEMINI.md / AGENTS.md 的先后只是审美问题不是引用替换不重命名examples/CLAUDE_MD_TESTING.md也不改其内容不修改 Gemini-CLI 专属的工具引用Phase D 候选。这三条与「Out of scope」章节互为补充前者防止实施时顺手扩大改动面后者防止把不属于本 phase 的引用一并处理——分 phase 推进的代价是过程变长收益是每一步都可独立验证、可独立回退。实施备注与当前仓库现状spec 末尾的 Implementation note 记录了一处计划外的增量Phase B 原计划三个提交覆盖 Claude-Code 之外的三个平台参考文档实际实施时又补了第四个参考文档references/claude-code-tools.md提交8505703让 Claude Code 的指令文件约定与工具名清单与其他平台并列存放而不是隐含在周边技能正文里。spec 承认这不在原计划内但与其意图一致。需要注意的是spec 是某一时间点的快照而参考文档集合此后仍在演化从当前仓库结构看using-superpowers/references/ 目录现有 codex-tools、gemini-tools、pi-tools、antigravity-tools 四份平台文档其中 gemini-tools.md 保留了 your instructions file 的解析说明而 codex-tools.md 等文档则承载了 subagent 调度、环境探测等其他平台差异。可以推断技能正文保持平台中立、差异下沉到 per-platform 参考文档 这一 Phase B 确立的架构被后续平台接入持续沿用。小结可复用的多平台文档中立化方法Phase B spec 虽然只改了两行文字但它示范了一套可复用的工程方法按引用类别分 phase——泛化措辞、配置文件、营销文案、工具名各自独立成文避免一次大改造成不可审计的混改白名单式 In/Out of scope——每处排除都附理由历史事实、示例有效性、多平台主张本身正确排除项即回归验证的预期值替换词选择有语义论证——your instructions file 与 instruction-file 都不是随手选的而是分别对应「不假设单一文件名」与「保持违规信号强度」两个诉求知识分层——技能正文只写平台无关的通用句在 X 平台上这句话对应哪个真实文件名由 per-platform 参考文档负责解析读者按需查阅grep 作为验收标准——grep -rn CLAUDE\.md skills/的残留集合被显式枚举任何后续提交引入新的平台专属引用都会在验证时暴露。对于维护任何跨 Agent 运行时的技能库、提示词包或插件仓库这套「中立正文 平台参考文档 枚举式 grep 验证」的组合都可以直接套用。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Superpowers 平台中立配置文件引用设计：多 Agent 运行时下「instructions file」的替换规则与落地验证
Superpowers 平台中立配置文件引用设计多 Agent 运行时下「instructions file」的替换规则与落地验证【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 插件需要同时运行在 Claude Code、Codex、Gemini CLI、OpenCode 等多个 Agent 运行时上不同运行时各自读取不同的指令文件CLAUDE.md、AGENTS.md、GEMINI.md。本文基于仓库中的设计文档 2026-05-05-platform-neutral-config-refs-design.md下称 Phase B spec完整讲解这一「平台中立配置文件引用」改造的背景、替换规则、提交与验证计划并结合当前仓库源码核实每一条规则的落地结果帮助读者掌握在多平台技能库中消除单平台假设的工程方法。背景从 Phase A 到 Phase B 的平台中立化分阶段推进Superpowers 的插件内容最初面向 Claude Code 编写随后被分发到多个 Agent 运行时。Phase A见 2026-05-05-platform-neutral-prose-design.md解决的是泛化的第三人称 “Claude” 措辞问题——把泛指「某个 agent」的句子改写为 your agent / the agent 等中性表达但明确把「配置文件引用」CLAUDE.md、AGENTS.md、GEMINI.md 的优先级列表与项目约定存放位置的提示划为 Phase B 的范围。Phase B 要处理的就是 Phase A 留下的下一类问题技能文件里把平台专属的指令文件当作唯一存在的写法。按 spec 的表述插件运行在多个 harness 上每个 harness 读取各自的指令文件当一个 skill 以「CLAUDE.md 是唯一文件」的姿态提及时这是一种 Claude-Code-centric 的假设在 Codex / Gemini CLI / OpenCode 上不成立。整个平台中立化工作按「引用类别」拆分成多个 phasePhase A 泛化措辞、Phase B 配置文件引用、Phase C 营销文案、Phase D 平台工具引用、Phase E 工具名引用每个 phase 独立成文、独立提交这是本文方法可以借鉴的关键点一次只处理一类引用规则边界清晰便于验证和回退。范围界定只改两处「活跃技能」中的 CLAUDE.md 引用spec 对 In scope 的定义非常克制——只针对活跃技能active skills中的两行具体文字skills/writing-skills/SKILL.md第 58 行——Project-specific conventions (put in CLAUDE.md)skills/receiving-code-review/SKILL.md第 30 行——Youre absolutely right! (explicit CLAUDE.md violation)而 Out of scope 部分逐一排除了容易被误伤的目标每一条都给出了不改的理由skills/using-superpowers/SKILL.md的用户指令优先级列表——该列表已经包容性地列出了全部三个文件名CLAUDE.md、GEMINI.md、AGENTS.md这是多平台插件对「什么才算用户指令」的真实主张本身正确无需修改。当前仓库中这条位于 using-superpowers/SKILL.mdUser instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior.历史 / 示例工件CREATION-LOG.md 中的归属路径~/.claude/CLAUDE.md是历史事实改写等于改写历史与 Phase A 对历史工件的处理原则一致CLAUDE_MD_TESTING.md 整个文件就是测试 CLAUDE.md 内容变体的完整示例文件名、正文以及 testing-skills-with-subagents.md 对它的引用都保持原样——「规范化它们反而会毁掉这个示例」。平台工具引用Gemini CLI 工具映射中提及 GEMINI.md 的内容——归入 Phase D 候选不在本阶段处理。这种「白名单式」的范围界定配合后文的 grep 验证构成了 spec 可执行性的核心。替换规则两条规则各对应一处修改spec 为两处修改各给出一条独立规则并解释了为什么选这个措辞而不是另一个候选词。规则 1「项目特定约定该放哪里」→ 使用通用短语针对writing-skills/SKILL.md:58Before:Project-specific conventions (put in CLAUDE.md)After:Project-specific conventions (put in your instructions file)spec 给出的决策依据是用通用短语而不是挑选某一个文件名。不同 harness 读取不同文件CLAUDE.md、AGENTS.md、GEMINI.md 等技能不应假设其中任何一个而「每个平台的首选文件名」应该由平台工具参考文档references/{codex,copilot,gemini}-tools.md一类文件来承载——即技能正文保持中立平台差异下沉到 per-platform 参考文档。当前仓库中该规则已落地writing-skills/SKILL.md 第 58 行的现文为- Project-specific conventions (put in your instructions file)它位于 Dont create for 列表中与「一次性方案」「别处已有充分文档的标准实践」并列——这条规则同时回答了「技能与用户指令文件的内容边界如何划分」项目特定约定不属于可复用技能应写入用户自己的 instructions file。规则 2「(explicit CLAUDE.md violation)」括注 → 「instruction-file violation」针对receiving-code-review/SKILL.md:30Before:Youre absolutely right! (explicit CLAUDE.md violation)After:Youre absolutely right! (explicit instruction-file violation)这条规则的微妙之处在于括注本身在做实事它告诉读者这句话不只是风格不好而是主动违反了大量用户写入指令文件的规则。spec 选择 instruction file 作为跨平台统称同时覆盖 AGENTS.md / CLAUDE.md / GEMINI.md理由是它既保留了原有信号强度又没有选定某个具体文件名也没有软化成 common 之类的模糊表述。当前仓库中 receiving-code-review/SKILL.md 第 30 行的现文为- Youre absolutely right! (explicit instruction-file violation)该行位于 Forbidden Responses 章节属于接收 code review 反馈时「绝不使用」的开场白清单之一与 Great point!表演性附和、Let me implement that now未验证就动手并列替换后的括注使这条禁令在所有平台上语义一致。参考文档承载平台差异的分工「技能正文中立 平台参考文档解析」这一分工在仓库中有实际体现。using-superpowers/SKILL.md 的 Platform Adaptation 章节按 harness 分派阅读- Codex: references/codex-tools.md - Pi: references/pi-tools.md - Antigravity: references/antigravity-tools.md其中 gemini-tools.md 第 24 行明确给出了 your instructions file 的平台解析When a skill mentions your instructions file, on Gemini CLI this isGEMINI.md. Gemini CLI loadsGEMINI.mdhierarchically: global at~/.gemini/GEMINI.md, project-level files in workspace directories and their ancestors, and sub-directoryGEMINI.mdfiles when a tool accesses files in those directories.这正好印证了规则 1 的设计意图读者在 Gemini CLI 上读到 your instructions file 时可以通过平台参考文档把它解析为真实文件名及其层级加载规则。提交计划与验证方案原子提交 grep 兜底提交计划spec 规划了三个按顺序执行的原子提交每个提交信息标注 Phase B 和切片名使提交序列自文档化writing-skills/SKILL.md——项目约定存放位置一行的 CLAUDE.md → your instructions filereceiving-code-review/SKILL.md——违规括注中的 CLAUDE.md → instruction-file平台工具参考文档——为每个references/{codex,copilot,gemini}-tools.md补上该平台的首选指令文件名CLAUDE.md、AGENTS.md、GEMINI.md 等使读者能把 your instructions file 解析为真实文件名。验证方法验证分为两个粒度全部基于阅读与 grep无测试代码每个提交后通读改动段落确认语法与语义仍然通顺grep -n CLAUDE\.md touched-file——活跃正文中不应再有残留命中已记录的 carve-out 除外。全部提交后grep -rn CLAUDE\.md skills/的返回结果应只剩已记录的例外集合CREATION-LOG、CLAUDE_MD_TESTING 及其入站引用、using-superpowers 中的优先级列表。这套验证方式可以直接在仓库中复核。对当前skills/目录执行等价的CLAUDE\.md检索命中恰好是且仅是 spec 预期的那几类例外systematic-debugging/CREATION-LOG.md——历史归属路径~/.claude/CLAUDE.mdusing-superpowers/SKILL.md——用户指令优先级列表writing-skills/testing-skills-with-subagents.md——指向示例的入站引用writing-skills/examples/CLAUDE_MD_TESTING.md——示例文件本身。也就是说活跃技能正文中已无裸 CLAUDE.md 引用验证结论与 spec 的预期完全一致。Non-goals明确「不做什么」spec 用三条非目标锁住了改动边界不调整using-superpowers/SKILL.md中优先级列表的顺序——CLAUDE.md / GEMINI.md / AGENTS.md 的先后只是审美问题不是引用替换不重命名examples/CLAUDE_MD_TESTING.md也不改其内容不修改 Gemini-CLI 专属的工具引用Phase D 候选。这三条与「Out of scope」章节互为补充前者防止实施时顺手扩大改动面后者防止把不属于本 phase 的引用一并处理——分 phase 推进的代价是过程变长收益是每一步都可独立验证、可独立回退。实施备注与当前仓库现状spec 末尾的 Implementation note 记录了一处计划外的增量Phase B 原计划三个提交覆盖 Claude-Code 之外的三个平台参考文档实际实施时又补了第四个参考文档references/claude-code-tools.md提交8505703让 Claude Code 的指令文件约定与工具名清单与其他平台并列存放而不是隐含在周边技能正文里。spec 承认这不在原计划内但与其意图一致。需要注意的是spec 是某一时间点的快照而参考文档集合此后仍在演化从当前仓库结构看using-superpowers/references/ 目录现有 codex-tools、gemini-tools、pi-tools、antigravity-tools 四份平台文档其中 gemini-tools.md 保留了 your instructions file 的解析说明而 codex-tools.md 等文档则承载了 subagent 调度、环境探测等其他平台差异。可以推断技能正文保持平台中立、差异下沉到 per-platform 参考文档 这一 Phase B 确立的架构被后续平台接入持续沿用。小结可复用的多平台文档中立化方法Phase B spec 虽然只改了两行文字但它示范了一套可复用的工程方法按引用类别分 phase——泛化措辞、配置文件、营销文案、工具名各自独立成文避免一次大改造成不可审计的混改白名单式 In/Out of scope——每处排除都附理由历史事实、示例有效性、多平台主张本身正确排除项即回归验证的预期值替换词选择有语义论证——your instructions file 与 instruction-file 都不是随手选的而是分别对应「不假设单一文件名」与「保持违规信号强度」两个诉求知识分层——技能正文只写平台无关的通用句在 X 平台上这句话对应哪个真实文件名由 per-platform 参考文档负责解析读者按需查阅grep 作为验收标准——grep -rn CLAUDE\.md skills/的残留集合被显式枚举任何后续提交引入新的平台专属引用都会在验证时暴露。对于维护任何跨 Agent 运行时的技能库、提示词包或插件仓库这套「中立正文 平台参考文档 枚举式 grep 验证」的组合都可以直接套用。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考