using-superpowers

概觀

using-superpowers 技能的用途

using-superpowers 技能是一個幫 AI agent 啟動對話的「開場技能」。它定義 agent 應該如何：

• 判斷何時要呼叫技能（在相關時，這不是可有可無的步驟）
• 在使用者提示、superpowers 技能與系統預設行為之間，決定指令優先順序
• 在 Claude Code、Gemini CLI 等不同平台上正確存取與啟用技能
• 將標準的「superpowers」工具名稱轉換成各平台的對應工具

這個技能設計用在任何新對話或新任務的起點。它建立一個共通約定：只要有哪怕一點機會某個技能適用，agent 就必須在回答之前先呼叫該技能，包含在提出釐清問題之前。

using-superpowers 適合哪些人

如果你符合以下情境，應該使用 using-superpowers 技能：

• 作為開發者，正在設定 Claude Code、Gemini CLI 或類似環境
• 維護一個多技能、多 agent 的工作區，並希望行為一致
• 將 obra/superpowers repository 作為標準技能程式庫
• 建置內部流程，希望 agent 遵守已文件化的流程並使用正確的工具

它尤其適用於大型專案——一旦漏掉相關技能（例如 code review 或規劃技能），就可能造成結果不一致，或忽略安全檢查。

這個技能解決的問題

using-superpowers 針對 agent 工作流程中常見的幾個問題提供解法：

• agent 直接「憑直覺」回答，而不是先檢查可用技能
• 對於使用者指令與技能到底誰比較「說了算」感到混淆
• 工具使用錯誤（例如直接讀技能檔案，而不是透過 Skill tool）
• Claude Code、Gemini CLI 與其他環境之間的平台差異

安裝並啟用 using-superpowers 後，可以降低這些不一致性，並清楚規範技能應該如何被發現與使用。

什麼情況適合或不適合使用 using-superpowers

適合使用的情境：

• 你倚賴多個技能，而且這些技能必須被一致地遵循
• 你希望 agent 在進行前一定會先檢查相關技能
• 你跨越多個平台運作，需要在工具名稱之間做對應
• 你正在建立或維護一個 superpowers 風格的技能程式庫

不適合使用的情境：

• 你是被派遣執行單一狹義任務的一次性 subagent（這個技能明確說 subagent 應該略過它）
• 你的環境非常精簡，幾乎沒有額外技能或工具整合
• 你希望完全自由、探索式的行為，不想要嚴格規則規範何時要呼叫技能

---

使用方式

1. 安裝 using-superpowers 技能

使用 Skills CLI 從 obra/superpowers repository 安裝 using-superpowers：

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

這會將 using-superpowers 的技能定義與相關參考資料拉進你的 skills 環境中。

安裝後，你至少會看到這些與此技能相關的檔案：

• SKILL.md — 主要行為與指令優先順序
• references/codex-tools.md — 適用 Codex 風格環境的工具對應
• references/gemini-tools.md — 適用 Gemini CLI 的工具對應

2. 了解 subagent 規則

這個技能包含一個 subagent 防護規則：

• 如果某個 agent 是作為 subagent 被派遣執行特定任務，它應該略過這個技能。
• 這能讓 subagent 專注於自己的任務，避免重新初始化全域技能行為。

身為工作流程設計者，你應該：

• 確保你的主要 agent會在對話一開始就呼叫 using-superpowers
• 設定 subagent，在被建立用來執行特定工作時，不要再次執行這個技能

3. 遵守指令優先順序模型

using-superpowers 定義了一個清楚的指令階層：

1. 使用者指令 — 最高優先權
   • 直接的使用者提示
   • 專案特定的檔案，如 CLAUDE.md、GEMINI.md、AGENTS.md
2. Superpowers 技能 — 包含 using-superpowers 與程式庫中的其他技能
3. 系統預設提示 / 模型預設行為 — 最低優先權

實務上代表：

• 若 CLAUDE.md 或 GEMINI.md 與某個技能內容衝突，以使用者檔案為準。
• Superpowers 技能可以覆寫模型預設行為，但不能違反使用者指令。
• 當沒有使用者指令或技能適用時，再由系統預設提示補上空缺。

在設定你的環境時，請確保這些來源都能被看到，並讓主要 agent 清楚這個優先順序。

4. 強制執行「必須呼叫技能」規則

using-superpowers 的核心規則之一，是只要相關，呼叫技能就是強制性的：

• 只要有哪怕 1% 的機會某個技能適用於目前任務，agent 就必須呼叫它。
• 當可能有相關技能時，agent 不應該在呼叫技能前就直接回答，或先詢問釐清問題。

這個規則的目的在於：

• 避免 agent 略過帶有重要安全或流程邏輯的技能
• 促進 skills-first 的工作方式：在即興發揮之前，先搜尋並使用適合的技能

身為開發者，你可以：

• 將此視為組織層級的 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 以外的環境：

• 參考你使用平台的官方文件，了解其如何處理 技能啟用 或 基於工具的工作流程。
• 使用此 repository 中提供的參考文件，將通用的「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 handling
  • Read / Write / Edit / Bash → 對應的 Codex 檔案與 shell 工具

文件也說明：

• 如何在 Codex 中啟用 multi-agent 支援：在 ~/.codex/config.toml 中加入：

[features]
multi_agent = true

• 當 Codex 沒有 named agent registry 時，如何處理具名 agent 派遣，包含讀取提示檔（例如 agents/code-reviewer.md）、填入 placeholder，並以該提示內容建立一個 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 的功能。
• 依賴 subagent 的技能（例如 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）
   • 了解工具對應方式以及不支援 subagent 的限制。

接著你可以依據自己的工具與設定檔，調整並套用這些模式。

---

常見問題（FAQ）

我要如何安裝 using-superpowers 技能？

使用 Skills CLI 從 obra/superpowers repository 新增這個技能：

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

安裝完成後，先開啟 SKILL.md 查看核心規則，再到 references/ 資料夾查看各平台的工具對應。

agent 應該在什麼時候執行 using-superpowers？

using-superpowers 設計給主要 agent 在對話或任務一開始就執行。適用的情境包含當 agent 即將：

• 開始在一個已導入 superpowers 技能的專案中工作
• 決定對新的請求要使用哪些技能
• 在多工具、多平台的開發環境中運作

被派遣執行狹義任務的 subagent 則應該略過這個技能，改為遵從傳遞給它的提示或指令。

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 就會遵守其中定義的指令優先順序與技能呼叫規則。

你可以搭配同一個 repository 中的其他技能，建立一個穩健、以技能為核心的開發流程。

using-superpowers 如何搭配 Gemini CLI 使用？

在 Gemini CLI 中：

• 使用 activate_skill tool 啟用技能。
• using-superpowers 說明 Gemini 會在 session 開始時載入技能中繼資料，並在需要時再載入完整內容。
• superpowers 技能中提到的工具名稱，會在 references/gemini-tools.md 中對應到 Gemini CLI 的工具。

請留意 Gemini CLI 不支援 subagents；倚賴 subagent 派遣的技能會自動退回單一工作階段的執行模式。

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

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

• 將 SKILL.md 視為行為與指令優先順序的權威來源。
• 參考 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 repository 中的其他技能，打造更完整的工作流程。

單靠 using-superpowers 就足夠了嗎？

using-superpowers 提供的是關於技能如何被發現與套用的基礎架構，但與同一生態系中的其他技能（例如規劃、code review、測試等）搭配時，威力才會完整展現。

建議將它作為 agent 設定的第一層，然後依專案需求，逐步加入領域特定的技能。