using-superpowers

概要

using-superpowers スキルでできること

using-superpowers スキルは、AI エージェント向けの「会話ブートストラッパー」です。このスキルは、エージェントが次のように振る舞うためのルールを定義します:

• いつスキルを呼び出すべきか を判断し、該当する場合はそれを「必須」にする
• ユーザーのプロンプト、superpowers スキル、デフォルトのシステム挙動の間で、指示の優先順位 を決める
• Claude Code や Gemini CLI など、異なるプラットフォーム上でスキルに 正しくアクセス・起動 する
• 標準的な「superpowers」ツール名を、各プラットフォーム固有のツール名に変換する

このスキルは、新しい会話やタスクの開始時 に利用することを想定しています。「少しでも関係しそうなスキルがあるなら、回答する前に必ずスキルを呼び出す」という共通ルールを確立します。これは、確認のための質問をする前でも同様です。

using-superpowers の対象ユーザー

次のような場合には、using-superpowers スキルの利用を検討してください:

• Claude Code や Gemini CLI などの環境を設定する 開発者
• 複数スキル・複数エージェント環境 を運用し、一貫した挙動を保ちたい
• obra/superpowers リポジトリを スキルの標準ライブラリ として使っている
• エージェントに ドキュメント化された手順を守らせ、適切なツールを使わせたい 内部ワークフローを構築している

特に、コードレビューや計画立案といった重要なスキルを呼び忘れることで、結果が不安定になったり安全チェックが抜け落ちたりしがちな、大規模なプロジェクトで有用です。

このスキルが解決する課題

using-superpowers スキルは、エージェントワークフローでよく起きる次のような問題に対処します:

• 利用可能なスキルを確認せず、エージェントが「カン」で回答してしまう
• ユーザーの指示とスキルの指示 のどちらが優先されるかが曖昧
• Skill ツールを使わずスキルファイルを直接読むなど、ツールの誤用が起きる
• Claude Code、Gemini CLI などプラットフォームごとの挙動やツール名の違い

using-superpowers を導入して有効化することで、これらのばらつきを減らし、「スキルをどう見つけ、どう使うべきか」を明確にできます。

using-superpowers が向いているケース／向いていないケース

向いているケース:

• 複数のスキルを、毎回同じルールで確実に適用したい
• エージェントに、処理を進める前に 常に関連スキルを確認させたい
• 複数プラットフォーム で動作させており、ツール名のマッピングが必要
• superpowers 型のスキルライブラリ を自作・運用している

向いていないケース:

• ごく限定されたタスクのために起動される 一時的なサブエージェント（このスキルはサブエージェントはスキップするよう明示しています）
• 追加のスキルやツール連携のない、最小構成だけで運用している
• スキルを呼び出すタイミングを厳密に決めず、完全に自由な探索的挙動をさせたい

---

使い方

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. サブエージェントに関するルールを理解する

このスキルには サブエージェント用のガード が定義されています:

• 特定タスクのために サブエージェントとして起動されたエージェント は、このスキルを スキップすべき とされています。
• これにより、サブエージェントは自身のタスクに集中でき、グローバルなスキル挙動の再初期化を避けられます。

ワークフロー設計者としては、次の点に注意してください:

• メインのエージェント が会話開始時に using-superpowers を呼び出すようにする
• サブエージェントは、特定のジョブのために生成されたときに、このスキルを 再実行しない ように設定する

3. 指示の優先順位モデルに従う

using-superpowers は、指示の優先順位に明確な階層を定義します:

1. ユーザーからの指示 — 最優先
   • ユーザーの直接的なプロンプト
   • CLAUDE.md、GEMINI.md、AGENTS.md などのプロジェクト固有ファイル
2. Superpowers スキル — using-superpowers やライブラリ内の他のスキル
3. デフォルトのシステムプロンプト／モデル既定挙動 — 最下位

実務上の意味としては:

• CLAUDE.md や GEMINI.md の内容とスキルの指示が衝突した場合、ユーザー側のファイルが優先 されます。
• Superpowers スキルがデフォルトモデルの挙動を上書きできるのは、ユーザーの指示と矛盾しない範囲のみ です。
• ユーザー指示やスキルが適用されない領域を、デフォルトのシステムプロンプトが補完します。

環境を設定する際は、これらすべての情報源がエージェントから見えるようにし、メインエージェントがこの優先順位を理解した状態で動くようにしてください。

4. スキル呼び出しを必須にする

using-superpowers の中核となるルールのひとつは、スキルの呼び出しが「条件を満たす場合は必須」であることです:

• 現在のタスクにスキルが適用できる可能性が 1% でもある 場合、エージェントはそのスキルを 必ず 呼び出す必要があります。
• 関連しそうなスキルが存在する可能性があるときは、エージェントは 回答したり確認質問を行ったりする前に スキルを呼び出すべきです。

このルールは次のことを目的としています:

• 重要な安全・ワークフロー上のロジックを持つスキルを、エージェントが「飛ばしてしまう」ことを防ぐ
• エージェントが即興で対応する前に、まず適切なスキルを探して利用するという skills-first アプローチを徹底する

開発者としては、次のように扱えます:

• これを組織内の エージェント利用ポリシーの一部 として位置づける
• 会話の初期ステップでは、回答に先立ってスキル呼び出しが行われる場合があることを、ユーザーに説明しておく

5. プラットフォームごとに正しいスキルアクセス方法を使う

using-superpowers は、プラットフォームごとのスキルアクセス方法を定義しています。

Claude Code

• スキルは Skill ツールを使って呼び出します。
• スキルが呼び出されると、その内容が読み込まれてエージェントに提示されます。エージェントはその内容に 直接従う 必要があります。
• スキルファイルを開くのに Read ツールを使ってはいけません。スキルアクセスには Skill ツールを使うべきです。

Gemini CLI

• スキルは activate_skill ツールで有効化します。
• Gemini はセッション開始時にスキルのメタデータを読み込み、要求時に完全なコンテンツを オンデマンドで 有効化します。
• スキルが有効化されたら、エージェントはそのスキルが提供する指示に従う必要があります。

その他の環境

Claude Code と Gemini CLI 以外の環境の場合:

• そのプラットフォームのドキュメントで、スキルの有効化 や ツールベースのワークフロー の扱いを確認してください。
• このリポジトリ内のリファレンスを、汎用的な「superpowers」ツール名を自分のプラットフォームのツールにマッピングする際の参考にしてください。

6. Codex 系環境へのツールマッピング

Codex CLI など Codex 系の環境を使っている場合は、次のファイルを参照してください:

• references/codex-tools.md

このリファレンスの要点:

• スキルはデフォルトで Claude Code のツール名 を利用します。
• ファイル内には、superpowers のツールと Codex の対応関係を示す マッピング表 が含まれています。例:
  • Task → spawn_agent
  • 複数の Task 呼び出し → 複数の spawn_agent 呼び出し
  • Task の結果 → wait
  • Task の完了 → close_agent
  • TodoWrite → update_plan
  • Skill → ネイティブな skills ハンドリング
  • Read / Write / Edit / Bash → 対応する Codex のファイル／シェルツール

また、次の内容も説明されています:

• ~/.codex/config.toml に以下を追加して、Codex で multi-agent support を有効にする方法:

[features]
multi_agent = true

• Codex に名前付きエージェントのレジストリがない場合の named agent dispatch の扱い方。具体的には、プロンプトファイル（agents/code-reviewer.md など）を読み込み、プレースホルダーを埋めて、そのプロンプトを使って worker エージェントを起動する流れが説明されています。

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 は サブエージェントをサポートしていない — Task ツールに相当する機能はありません。
• subagent-driven-development や dispatching-parallel-agents のようにサブエージェントに依存するスキルは、executing-plans など他の計画系スキルを利用した単一セッション実行に自動的にフォールバックします。
• Gemini CLI には、list_directory、save_memory、ask_user、tracker_create_task、enter_plan_mode / exit_plan_mode など、Claude Code には直接対応するものがない追加ツールも含まれています。

8. 推奨の読み進め方

新しいワークスペースで using-superpowers を最大限活かすための読み順は次の通りです:

1. まず SKILL.md を読む
   • 指示の優先順位と、スキル呼び出し必須ルールを理解します。
2. Codex や類似環境を使っている場合は references/codex-tools.md を開く
   • マルチエージェントサポートとツールマッピングを設定します。
3. Gemini CLI を使っている場合は references/gemini-tools.md を開く
   • ツールマッピングやサブエージェント非対応である点を把握します。

そのうえで、自分のツールや設定ファイルに合わせて、これらのパターンを応用してください。

---

FAQ

using-superpowers スキルはどうやってインストールしますか？

Skills CLI を使って、obra/superpowers リポジトリから追加します:

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

インストールが完了したら、コアとなるルールは SKILL.md で、プラットフォーム固有のツールマッピングは references/ フォルダで確認できます。

エージェントはいつ using-superpowers を実行すべきですか？

using-superpowers スキルは、メインエージェントが 会話やタスクを開始するとき に実行されることを想定しています。エージェントが次のようなタイミングで使うのが適しています:

• superpowers スキルが設定されたプロジェクトで作業を始めるとき
• 新しいリクエストに対して、どのスキルを使うか決めるとき
• 複数ツール・複数プラットフォームが混在した開発環境で動作するとき

限定的なタスクのために呼び出されたサブエージェントは、このスキルを スキップ し、渡されたプロンプトや指示に従うだけにするべきです。

using-superpowers はユーザーの指示を上書きしますか？

いいえ。スキル内で明示されている通り、ユーザーの指示が常に最優先 です。指示の優先順位は次の通りです:

1. ユーザーからの指示（CLAUDE.md、GEMINI.md、AGENTS.md、ユーザーの直接プロンプトなど）
2. using-superpowers を含む superpowers スキル
3. デフォルトのシステムプロンプト

ユーザーの指示とスキルの内容が衝突する場合、エージェントは必ずユーザーの指示に従わなければなりません。

「mandatory skill invocation」とは実際にはどういう意味ですか？

mandatory skill invocation（スキル呼び出し必須）とは、次のような運用を指します:

• 現在のタスクにスキルが適用できる 現実的な可能性が少しでもある 場合、エージェントはそのスキルを呼び出す必要があります。
• 関連スキルが存在しうる場面では、エージェントはまずスキルを呼び出し、先に回答したり確認質問をしたりしてはいけません。

これにより次のことが保証されます:

• 安全性やワークフローに関わるスキルが、常に漏れなく適用される
• エージェントが独自判断で処理するのではなく、検証済みの手順に基づいて動作する

using-superpowers は Claude Code にどのような影響がありますか？

Claude Code では次のように挙動します:

• エージェントは Skill ツールを使って、using-superpowers を含む各種スキルを読み込み、その内容に従います。
• スキルファイルを直接開くために Read ツールを使うべきではありません。
• using-superpowers が有効になった後は、そのガイドラインに従って、指示の優先順位やスキル呼び出しのルールが適用されます。

同じリポジトリ内の他のスキルと組み合わせることで、スキル駆動の堅牢な開発ワークフローを構築できます。

using-superpowers は Gemini CLI ではどう動作しますか？

Gemini CLI では次のように扱われます:

• スキルは activate_skill ツールで有効化します。
• using-superpowers では、Gemini がセッション開始時にスキルメタデータを読み込み、要求に応じて完全なコンテンツを有効化することを説明しています。
• superpowers スキルで参照されるツール名は、references/gemini-tools.md 内で Gemini CLI のツールにマッピングされています。

なお、Gemini CLI は サブエージェントをサポートしていません。そのため、サブエージェントのディスパッチに依存するスキルは、自動的に単一セッションでの実行パターンにフォールバックします。

他のエージェントプラットフォームでも using-superpowers は使えますか？

はい。プラットフォームに skill や tool の概念があれば利用できます:

• 挙動と指示の優先順位については SKILL.md を「仕様の原本」として扱ってください。
• references/codex-tools.md と references/gemini-tools.md を見て、superpowers のツール名を各プラットフォームのツールへマッピングする例として参考にしてください。
• 自分のプラットフォームのツール群とスキルの期待を整合させるために、同様のマッピングレイヤーを実装します。

プラットフォームの機能に応じて、マッピングを調整・拡張する必要がある場合もあります。

スキルをインストールしたあと、最初にどのファイルを読むべきですか？

実務的なセットアップを素早く行うには、次の順番がおすすめです:

1. SKILL.md — 基本挙動、指示の優先順位、スキル呼び出し必須ルール
2. references/codex-tools.md — Codex または Codex 類似の環境を使う場合
3. references/gemini-tools.md — Gemini CLI を使う場合

その後、obra/superpowers リポジトリ内の他のスキルも確認し、より包括的なワークフローを構築していくとよいでしょう。

using-superpowers だけで十分ですか？

using-superpowers は、スキルの発見と適用方法の 土台 を提供するスキルです。真価を発揮するのは、同じエコシステム内の他のスキル（計画、コードレビュー、テストなど）と組み合わせて使ったときです。

エージェント構成の第一層として using-superpowers を導入し、その上にプロジェクトに適したドメイン固有スキルを重ねていく構成をおすすめします。