using-superpowers

概览

using-superpowers 技能的作用

using-superpowers 是面向 AI agents 的对话引导技能（conversation bootstrapper）。它定义了一个 agent 应该如何：

• 决定何时调用技能（在相关时必须调用，而不是可选）
• 在用户指令、superpowers 技能和系统默认行为之间确定指令优先级
• 在 Claude Code、Gemini CLI 等不同平台上正确访问和激活技能
• 将标准化的 “superpowers” 工具名称映射到各平台的等价工具

这个技能应在每个新对话或任务开始时使用。它建立了一份共享契约：只要某个技能有哪怕一点点可能适用，agent 就必须在回答之前调用该技能——包括在提出澄清问题之前。

适合使用 using-superpowers 的用户

在以下场景中，你应该使用 using-superpowers 技能：

• 你是配置 Claude Code、Gemini CLI 或类似环境的开发者
• 你维护一个多技能、多 agent 的工作空间，需要统一行为
• 你把 obra/superpowers 仓库当作技能标准库来使用
• 你在搭建内部工作流，希望 agent 遵循文档化流程并使用正确工具

它在较大的项目中尤其有用——一旦漏掉某个相关技能（例如代码审查或规划类技能），可能会导致结果不一致，甚至跳过关键的安全检查。

这个技能解决了哪些问题

using-superpowers 专门针对 agent 工作流中常见的几类问题：

• agent 靠“直觉”回答，而不是先检查可用技能
• 不清楚用户指令和技能指令谁更权威
• 工具使用不当（例如直接读技能文件，而不是通过 Skill tool 调用）
• Claude Code、Gemini CLI 等不同环境之间的差异

通过安装并激活 using-superpowers，你可以显著减少这些不一致行为，并明确技能应该如何被发现和使用。

using-superpowers 适用与不适用的场景

适用场景：

• 你依赖多个必须一致遵守的技能
• 你希望 agent 在执行前总是先检查是否存在相关技能
• 你在多平台上工作，需要统一的工具名称映射
• 你在构建或维护一个 superpowers 风格的技能库

不适用场景：

• 你是为某个极窄任务调度的一次性 subagent（该技能明确要求 subagent 跳过它）
• 你的环境非常简单，没有额外技能或工具集成
• 你希望完全自由、探索式的 agent 行为，不想对何时调用技能设定严格规则

---

使用方式

1. 安装 using-superpowers 技能

通过 Skills CLI 从 obra/superpowers 仓库安装 using-superpowers：

npx skills add https://github.com/obra/superpowers --skill using-superpowers

这会将 using-superpowers 的技能定义及相关参考资料拉取到你的技能环境中。

安装完成后，你至少应该能看到以下几个与该技能相关的文件：

• SKILL.md — 核心行为与指令优先级规则
• references/codex-tools.md — 面向 Codex 风格环境的工具映射
• references/gemini-tools.md — 面向 Gemini CLI 的工具映射

2. 理解 subagent 规则

该技能内置了一个 subagent 保护规则（subagent guard）：

• 如果某个 agent 是作为 subagent 被派发来完成特定任务，那么它应当跳过这个技能。
• 这样可以让 subagent 专注于自身任务，避免重复初始化全局技能行为。

作为工作流设计者，你需要：

• 确保你的主 agent在对话开始时调用 using-superpowers
• 配置 subagents，使其在被创建用于特定任务时不要重新运行该技能

3. 遵循指令优先级模型

using-superpowers 定义了一套清晰的指令层级结构：

1. 用户指令 — 最高优先级
   • 用户的直接输入
   • 项目级文件，如 CLAUDE.md、GEMINI.md、AGENTS.md
2. Superpowers 技能 — 包括 using-superpowers 和库中的其他技能
3. 系统默认提示 / 模型默认行为 — 最低优先级

在实践中，这意味着：

• 如果 CLAUDE.md 或 GEMINI.md 与某个技能的指令冲突，用户文件优先。
• Superpowers 技能可以覆盖模型默认行为，前提是不与用户指令冲突。
• 当用户指令和技能都未覆盖时，才由系统默认提示来补足。

在配置环境时，应确保这些信息源都对主 agent 可见，并明确这一优先顺序。

4. 强制执行“必须调用技能”的规则

using-superpowers 的核心原则之一，是在相关时技能调用必须是强制性的（mandatory）：

• 只要某个技能对当前任务存在哪怕 1% 的适用可能，agent 就必须调用它。
• 当技能可能适用时，agent 不应先回答或先提澄清问题，而是要先调用相关技能。

制定这一规则是为了：

• 防止 agent “跳过”那些承载关键安全逻辑或工作流逻辑的技能
• 鼓励 skills-first 的工作方式，让 agent 在“即兴发挥”前先搜索并使用合适技能

作为开发者，你可以：

• 将这一规则写入你的组织级 agent 使用规范
• 向终端用户说明：在对话早期，agent 可能会先调用相关技能，再给出回答

5. 按平台使用正确的技能访问方式

using-superpowers 定义了在不同平台上访问技能的规范。

Claude Code

• 使用 Skill tool 调用技能。
• 技能被调用后，其内容会被加载并展示给 agent，agent 应当直接遵循其中的指令。
• agent 不应使用 Read tool 直接打开技能文件，而是要通过 Skill tool 来访问。

Gemini CLI

• 通过 activate_skill tool 激活技能。
• Gemini 会在会话开始时加载技能元数据，然后在需要时按需激活完整内容。
• 技能被激活后，agent 应遵循该技能提供的指令。

其他环境

对于 Claude Code 和 Gemini CLI 之外的环境：

• 查阅你的平台文档，了解其对 skill activation 或 tool-based workflows 的支持方式。
• 使用本仓库中的参考文档，将通用的 "superpowers" 工具名称映射到你平台中的对应工具。

6. 为 Codex 风格环境映射工具

如果你使用 Codex CLI 或类似环境，请阅读：

• references/codex-tools.md

该文档中的关键点包括：

• 技能默认使用 Claude Code 工具名称。
• 文档提供了一张 映射表，将 superpowers 工具与 Codex 的等价工具对应起来，例如：
  • Task → spawn_agent
  • 多次 Task 调用 → 多次 spawn_agent 调用
  • Task result → wait
  • Task completion → close_agent
  • TodoWrite → update_plan
  • Skill → 原生 skills 机制
  • Read / Write / Edit / Bash → 对应的 Codex 文件与 shell 工具

文档还说明了：

• 如何通过修改 ~/.codex/config.toml 开启 multi-agent support：

[features]
multi_agent = true

• 在 Codex 不具备命名 agent 注册表时，如何处理按名称调度 agent：包括读取提示文件（如 agents/code-reviewer.md）、填充占位符，并以该提示内容启动一个 worker agent。

7. 为 Gemini CLI 映射工具

在 Gemini CLI 中使用时，请阅读：

• references/gemini-tools.md

该文档说明了标准 superpowers 工具与 Gemini CLI 工具的映射关系，例如：

• Read → read_file
• Write → write_file
• Edit → replace
• Bash → run_shell_command
• Grep → grep_search
• Glob → glob
• TodoWrite → write_todos
• Skill → activate_skill
• WebSearch → google_web_search
• WebFetch → web_fetch

文档还指出：

• Gemini CLI 不支持 subagents —— 没有等价的 Task tool。
• 依赖 subagents 的技能（如 subagent-driven-development 或 dispatching-parallel-agents）会退化为通过其他规划类技能（如 executing-plans）在单会话内执行。
• Gemini CLI 还包含一些在 Claude Code 中没有直接等价物的工具，如 list_directory、save_memory、ask_user、tracker_create_task，以及 enter_plan_mode / exit_plan_mode 等。

8. 推荐阅读顺序

如果你在一个新工作空间中引入 using-superpowers，推荐的阅读顺序是：

1. 先看 SKILL.md
   • 了解指令优先级和技能必须调用的规则。
2. 打开 references/codex-tools.md（如果你使用 Codex 或类似环境）
   • 配置 multi-agent 支持和工具映射。
3. 打开 references/gemini-tools.md（如果你使用 Gemini CLI）
   • 理解工具映射以及 Gemini 不支持 subagent 的限制。

之后，你可以将这些模式迁移到自己的工具和配置文件中。

---

常见问题（FAQ）

如何安装 using-superpowers 技能？

使用 Skills CLI，从 obra/superpowers 仓库添加该技能：

npx skills add https://github.com/obra/superpowers --skill using-superpowers

安装完成后，先阅读 SKILL.md 了解核心规则，再查看 references/ 目录下与平台相关的工具映射文档。

agent 应该在什么时候运行 using-superpowers？

using-superpowers 设计用于在主 agent 的对话或任务开始阶段运行。适用的时机包括：

• 即将开始在一个带有 superpowers 技能的项目中工作
• 需要为新的请求选择应当使用哪些技能
• 在一个多工具、多平台的开发环境中工作

被派发去执行窄范围任务的 subagents 应当跳过这个技能，改为遵循传递给它们的 prompt 或具体指令。

using-superpowers 会覆盖用户指令吗？

不会。该技能明确说明：用户指令总是优先。指令优先级如下：

1. 用户指令（包括 CLAUDE.md、GEMINI.md、AGENTS.md 以及用户的直接输入）
2. 像 using-superpowers 这样的 superpowers 技能
3. 系统默认提示行为

如果用户指令与某个技能的指令发生冲突，agent 必须遵循用户指令。

“必须调用技能”在实践中意味着什么？

“必须调用技能”意味着：

• 只要有任何现实可能性表明某个技能适用于当前任务，agent 就必须调用该技能。
• 在可能存在相关技能的情况下，agent 不应先回答或先提出澄清问题。

这有助于确保：

• 安全相关和流程相关的技能能够被稳定应用
• agent 优先依赖已验证的流程，而不是随意发挥

using-superpowers 会如何影响 Claude Code？

在 Claude Code 中：

• agent 应使用 Skill tool 来加载并遵循技能（包括 using-superpowers）。
• 不应使用 Read tool 直接打开技能文件。
• 一旦 using-superpowers 生效，agent 将遵循其中关于指令优先级和技能调用的指南。

你可以将该技能与同一仓库中的其他技能组合使用，构建一个以技能为中心的稳健开发工作流。

using-superpowers 在 Gemini CLI 中如何工作？

在 Gemini CLI 中：

• 使用 activate_skill tool 来激活技能。
• using-superpowers 说明了 Gemini 如何在会话开始时加载技能元数据，以及在被请求时激活完整内容。
• superpowers 技能中引用的工具名称，会在 references/gemini-tools.md 中映射到具体的 Gemini CLI 工具。

需要注意的是，Gemini CLI 不支持 subagents；依赖 subagent 调度的技能会自动退化为单会话执行模式。

我可以在其他 agent 平台中使用 using-superpowers 吗？

可以，只要你的平台支持 skills 或 tools 概念：

• 使用 SKILL.md 作为行为与指令优先级的单一事实来源（source of truth）。
• 参考 references/codex-tools.md 和 references/gemini-tools.md，了解如何将 superpowers 工具名称映射到你的平台。
• 实现类似的映射层，使平台工具与技能预期对齐。

根据平台能力，你可能需要对映射关系做一定调整或扩展。

安装技能后，我应该先看哪些文件？

如果你想快速完成实用配置，推荐顺序如下：

1. SKILL.md — 核心行为、指令优先级和“必须调用技能”的规则。
2. references/codex-tools.md — 如果你使用 Codex 或类似环境。
3. references/gemini-tools.md — 如果你使用 Gemini CLI。

随后，你可以继续探索 obra/superpowers 仓库中的其他技能，搭建更完整的工作流。

单独使用 using-superpowers 够吗？

using-superpowers 提供的是技能发现与应用方式的基础层，本身并不是“万能技能”。当它与同一生态中的其他技能（如规划、代码审查、测试等）结合使用时，价值会更大。

建议将它作为 agent 配置的第一层，然后根据项目需要叠加具体领域的技能。