Superpowers を Codex で使う — 導入手順と収録スキル

Superpowers とは — 開発の進め方を言語化したスキル集

Superpowers は、開発者の Jesse Vincent 氏(GitHub アカウント obra)が公開しているスキル集で、AI コーディングエージェントに対して「作業をどう進めるべきか」を教える文書群だ(出典: https://github.com/obra/superpowers )。収録されているのは、コードを書き始める前のブレインストーミング、実装計画の作成、計画に沿った段階的な実行、テストを先に書くテスト駆動開発、思いつきの修正を禁じて根本原因を突き止める体系的デバッグなど、いずれも「特定のライブラリの使い方」ではなく「開発という仕事の型」に踏み込んだものばかりだ。エージェントは能力が高くても、放っておくと計画を飛ばしていきなりコードを書き、失敗すると場当たり的な修正を重ねがちだ。Superpowers はその癖をスキルの形で矯正しようという試みであり、公開直後から AI コーディングエージェントのユーザーの間で広く参照されてきた。

収録スキルの傾向 — 計画・実装・デバッグの三本柱

収録スキルはおおまかに三つの系統に分けられる。第一に「作る前」の系統で、要件を対話で掘り下げるブレインストーミングや、実装前に詳細な計画文書を書き起こすスキルがある。第二に「作る最中」の系統で、テストを先に書いて赤から緑へ進むテスト駆動開発、計画をフェーズ単位で消化していく実行スキルが該当する。第三に「詰まったとき」の系統で、症状への対症療法を禁じ、原因を特定してから直す体系的デバッグがここに入る。三系統がそろっているため、開発の入口から出口までを一貫した型で通せるのが強みだ(出典: https://github.com/obra/superpowers )。

なぜ Codex ユーザーがいま注目すべきか

Superpowers は Claude Code 向けに生まれたが、状況は 2025 年末から変わった。Codex がスキル(Skills)機能に対応し、SKILL.md という共通の書式でエージェントの手順を記述する流れが、ツールの垣根を越えて広がったからだ。OpenAI 自身も公開カタログ openai/skills を整備し、スキルを「書いて、置いて、呼び出す」使い方が Codex の標準機能として定着している(出典: https://github.com/openai/skills )。その結果、他のエージェント向けに蓄積されたスキル資産を Codex に持ち込むという選択肢が現実味を帯びており、Superpowers はその代表格にあたる。

Codex で使える理由 — SKILL.md の共通規格

Superpowers のスキルが Codex で読み込める根拠は、書式の互換性にある。Codex の公式ドキュメントは、スキルが特定製品専用ではなく公開された共通規格(open agent skills standard)に沿うことを明記しており、SKILL.md の先頭に YAML 形式で name と description を書き、本文に手順を記すという構造は Superpowers の各スキルとまったく同じだ(出典: https://developers.openai.com/codex/skills )。Codex は作業フォルダ直下の .agents/skills、リポジトリのルート、ユーザー個人の $HOME/.agents/skills、管理者向けの /etc/codex/skills という順に複数の場所を走査してスキルを発見するため、Superpowers のスキルフォルダをこのいずれかに置くだけで認識の対象になる。読み込みも段階的で、Codex はまず各スキルの名前と説明だけを把握し、使うと判断したときに初めて本文を読む。したがってスキルを数十個まとめて導入しても、会話の文脈を最初から圧迫する心配は小さい。

どこに置くか — ホーム配下とリポジトリ配下の使い分け

置き場所は「誰に使わせたいか」で決める。自分のあらゆるプロジェクトで Superpowers の型を効かせたいなら、$HOME/.agents/skills に置くのが素直だ。特定のプロジェクトだけで試したい、あるいはチームで共有したいなら、リポジトリの .agents/skills に入れてコミットすれば全員に行き渡る。Codex は狭い範囲の置き場所を優先するため、ホーム配下に全体を入れつつ、プロジェクト側で一部のスキルだけ書き換えて上書きする、という段階的な運用もできる(出典: https://developers.openai.com/codex/skills )。

導入手順 — リポジトリを取得して配置する

導入は難しくない。必要なのは Git と、Skills 対応済みの Codex(CLI・IDE 拡張のいずれでもよい)だけだ。以下ではユーザー個人のスキルとして導入する手順を示す。

1. リポジトリを取得する: 任意の作業用フォルダで git clone https://github.com/obra/superpowers.git を実行し、リポジトリ一式を手元に置く(出典: https://github.com/obra/superpowers )。
2. スキルの場所を確かめる: リポジトリ内のスキル群のフォルダ構成を確認する。各スキルは SKILL.md を含むフォルダ単位で構成されているので、どのスキルを持ち込むかをここで選別する。
3. .agents/skills に配置する: mkdir -p ~/.agents/skills で置き場所を作り、選んだスキルのフォルダをコピーする。リポジトリの更新に追従したい場合は、コピーの代わりにシンボリックリンクを張っておくと git pull だけで最新化できる。
4. Codex から認識を確認する: Codex CLI を起動し、/skills コマンドまたは $ の入力からスキル一覧を開いて、導入したスキルの名前が並んでいるかを確かめる(出典: https://developers.openai.com/codex/skills )。
5. 明示的に呼び出して試す: まずは $スキル名 で直接指名し、意図した手順どおりに Codex が振る舞うかを小さなタスクで検証する。問題がなければ、以後は依頼内容に応じた暗黙の選択にも任せられる。

動作確認のコツ — description が発動精度を決める

導入後にスキルがうまく発動しない場合、最初に疑うべきは各スキルの description だ。Codex は依頼内容とスキルの説明文を突き合わせて使うかどうかを判断するため、説明が英語で抽象的なままだと、日本語の依頼に対して選ばれにくいことがある。よく使うスキルについては、description に「どんな依頼のときに使うか」を日本語で追記しておくと、暗黙の選択の精度が目に見えて変わる。本文はそのままでも、説明文の調整だけで使い勝手が大きく改善するので、導入直後にひと手間かける価値がある。

どのスキルから試すか — 汎用性の高い順に

全部を一度に導入する必要はない。Codex で使う前提なら、実行環境への依存が薄く、文章としての指示だけで完結するスキルから試すのが安全だ。ここでは系統ごとに最初の候補を挙げる。

まずはブレインストーミングと実装計画

最初に試す価値があるのは「作る前」の系統だ。ブレインストーミングのスキルは、要件を一問一答で掘り下げてから設計に進むという対話の型を Codex に与えるもので、環境固有の機能を使わないため互換性の問題がほぼ起きない。実装計画のスキルも同様に、着手前に計画文書を書かせて人間の確認を挟むという流れを作れる。Codex に大きめのタスクを任せると、いきなりコードを書き始めて方向を誤ることがあるが、この二つを通すだけで「合意してから書く」動きに変わるのを体感できるはずだ(出典: https://github.com/obra/superpowers )。

テスト駆動開発と体系的デバッグ

次に効くのが「作る最中」と「詰まったとき」の系統だ。テスト駆動開発のスキルは、失敗するテストを先に書き、それを通す最小の実装を行い、その後に整理するという順序を強制する。Codex は指示がなければテストを後回しにすることがあるため、この型を常に効かせたい人には導入の価値が大きい。体系的デバッグのスキルは、エラーに対して思いつきの修正を重ねることを明確に禁じ、再現手順の確立と原因の特定を先に要求する。長時間のセッションで修正が空回りし始めたときほど効果がわかりやすい。

注意点 — そのまま動かないスキルもある

導入にあたって理解しておくべき制約が三つある。第一に、Superpowers は Claude Code 向けに書かれた歴史があるため、一部のスキルはもとの実行環境の固有機能——たとえば特有のサブエージェントの起動方法や、その環境にしかないコマンド——を本文中で前提にしていることがある。こうしたスキルは Codex 上では該当機能が見つからず、期待どおりに動かない。SKILL.md は素の Markdown なので、導入前に本文へ目を通し、環境固有の記述があれば Codex の同等機能(サブエージェントや並列実行の指示など)に読み替えて書き換えるとよい。第二に、スキルは著者の開発思想を色濃く反映した文書であり、テスト駆動開発の厳格さなどはプロジェクトの方針と衝突する場合がある。合わない部分は遠慮なく削るか書き換えるのが正しい使い方だ。第三に、リポジトリは継続的に更新されるため、コピーで導入した場合は定期的な取り込み直しが必要になる。利用条件についてはリポジトリのライセンス表記を導入前に確認しておきたい(出典: https://github.com/obra/superpowers )。

AGENTS.md との住み分け — 常時の方針か、呼び出す手順か

Superpowers を導入すると、「この内容は AGENTS.md に書くべきでは」と迷う場面が出てくる。判断基準は適用の常時性だ。リポジトリで常に守らせたい規約や方針は AGENTS.md に書き、ブレインストーミングやデバッグのように「その場面が来たときだけ」効かせたい手順はスキルのままにしておく(出典: https://developers.openai.com/codex/concepts/customization )。Superpowers の中身はほぼ後者に属するため、基本はスキルとして持ち、そこから抽出した数行の原則だけを AGENTS.md に昇格させる、という整理が扱いやすい。

openai/skills カタログとの併用

Superpowers だけがスキルの供給源ではない。OpenAI の公開カタログ openai/skills にはキュレーション済みのスキルがそろっており、Codex 内から $skill-installer で取り込める(出典: https://github.com/openai/skills )。カタログ側は個別ツールの連携や定型作業のスキルが中心で、開発の進め方を型にする Superpowers とは守備範囲が重ならない。両方を併用し、方法論は Superpowers、個別機能はカタログ、と使い分けるのが現時点での実用的な構成だ。

まとめ — スキル資産はツールを越えて持ち運べる

Superpowers は、ブレインストーミング・実装計画・テスト駆動開発・体系的デバッグといった開発の型を SKILL.md として言語化したスキル集であり、共通規格に沿っているため Codex でもそのまま読み込める。導入は obra/superpowers を取得して $HOME/.agents/skills かリポジトリの .agents/skills に置き、/skills で認識を確認して $スキル名 で試すだけだ。まずは環境依存のない「作る前」のスキルから始め、説明文の日本語化や環境固有記述の読み替えで手元に馴染ませていけばよい。スキルという共通の書式が広がったことで、他のエージェント向けに蓄積された知見を Codex に持ち込める時代になった。Superpowers はその恩恵を最初に体感できる素材だ(出典: https://developers.openai.com/codex/skills / https://github.com/obra/superpowers )。