superpowers のSKILL.mdを全部読んだので中身を解説する

Claude Code のスキルフレームワーク「superpowers」の SKILL.md を全部読みました。「使い方」の記事は山ほどあるのですが、中で何が起きているのかを解説した記事が見当たらなかったので、コードリーディング形式でまとめます。

想定読者

• superpowers を使っているが内部動作が気になる人
• 自作スキルを書きたい・書き始めた人
• AIエージェントのプロンプトエンジニアリング技法に興味がある人
• 「完全ガイド」は読んだが物足りない中〜上級者

参考：公式リソース

• obra/superpowers GitHub リポジトリ（v5.0.5、約107k Stars）
• Claude Code Skills 公式ドキュメント
• obra ブログ: Superpowers 5
• Anthropic マーケットプレイス（2026年1月15日に公式採用）

superpowers とは何か

superpowers は Jesse Vincent（@obra）が開発した、Claude Code 向けのスキルフレームワークです。K-9 Mail の開発者であり Perl のリリースマネージャでもあった obra が、「AIコーディングエージェントはもう十分賢い。足りないのは、プロの開発者がやるような作業の進め方だ」という問題意識から作ったものです。

中身は全14個のスキル（Markdownファイル）で構成されています。TDD、ブレインストーミング、デバッグ、サブエージェント開発など、開発ワークフロー全体をカバーしています。

この記事では、それらの SKILL.md を実際に読みながら「なぜこう書いてあるのか」「この設計で何が起きるのか」を掘り下げていきます。

起動の瞬間

superpowers をインストールして Claude Code を起動すると、最初に何が起きるのか。答えは hooks/hooks.json にあります。

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|clear|compact",
      "hooks": [{
        "type": "command",
        "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
        "async": false
      }]
    }]
  }
}

セッション開始時に session-start スクリプトが実行されます。ここで注目すべきは2つ。

async: false（同期実行） にしている点。v4.3.0 以前は async: true だったのですが、モデルの最初のレスポンスがスキル注入より先に生成されるレースコンディションが発生しました。superpowers なしの素のClaude が最初の1ターンだけ応答してしまう問題です。

matcher に resume が含まれていない点。v5.0.3 で追加された変更です。--resume でセッションを再開すると、会話履歴にすでにスキルコンテキストが入っているので、二重注入になってしまうんですよね。

session-start スクリプトの核心部分はこちら。

session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill...**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"

if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
else
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
fi

やっていることはシンプルです。using-superpowers/SKILL.md の全文を読み込んで、<EXTREMELY_IMPORTANT> タグで包んで、Claude のコンテキストに注入する。プラットフォーム（Claude Code / Cursor / その他）を検出して、出力先のJSONフィールドを切り替えています。

ちなみに heredoc ではなく printf を使っているのは、macOS の Homebrew bash 5.3+ で大きな変数展開を含む heredoc がハングするバグを回避するためです（Issue #571）。こういう実運用で踏んだ地雷の修正跡がリポジトリのあちこちに残っていて、なかなか味わい深いです。

門番としての using-superpowers

using-superpowers/SKILL.md は superpowers の中で最も重要なファイルです。セッション開始時に全文がコンテキストに注入される唯一のスキルで、他の全スキルの「門番」として機能します。

核心はこの部分。

<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a skill might apply to what you are doing,
you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</EXTREMELY-IMPORTANT>

1%でも該当する可能性があるなら、絶対にスキルを呼び出せ。かなり強い言い方ですが、これには理由があります。

LLM は「スキルを使わない」方向にバイアスがかかりやすいんです。面倒なプロセスを飛ばして直接回答した方が「効率的」に見えるから。そこで superpowers は、スキルをスキップしようとする際の典型的な合理化パターンを12個リストアップして、事前に潰しています。

Red Flags テーブル（12項目）

このテーブル、読むと「なるほど」となります。「まず情報を集めてから」「これはシンプルだからスキル不要」「スキルの内容は覚えてる」——全部、LLM が実際に使う言い訳です。それぞれに対して「情報収集のやり方をスキルが教えてくれる」「スキルは進化する、今のバージョンを読め」と具体的に反論しています。

もう一つ重要な設計があります。

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-STOP>

この1行がないと、サブエージェントとして起動された Claude が毎回スキルチェックに入ってしまい、パフォーマンスが劣化します。たった3行で無限再帰を防いでいるわけです。

スキルの優先順位

using-superpowers はスキル間の優先順位も定義しています。

1. プロセススキルを先に（brainstorming, debugging）→「どうアプローチするか」を決める
2. 実装スキルを後に（frontend-design, mcp-builder）→ 実行をガイドする

さらに、ユーザーの指示との優先順位も明確です。

1. ユーザーの明示的指示（CLAUDE.md 等）→ 最優先
2. Superpowers スキル → デフォルト動作をオーバーライド
3. デフォルトシステムプロンプト → 最低優先

CLAUDE.md に「TDD は使わない」と書けば、superpowers の TDD スキルより優先されます。この階層構造は意図的な設計で、ユーザーが常にコントロールを持てるようになっています。

TDD スキルの構造的強制

test-driven-development/SKILL.md は、superpowers の設計思想が最もよく表れているスキルです。

冒頭にこう書いてあります。

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

これが「Iron Law（鉄則）」と呼ばれるもので、superpowers の複数のスキルに共通するパターンです。

ただ、ルールを宣言しただけでは LLM は守りません。だから superpowers はルールを破ったときの対処まで構造化しています。

Write code before the test? Delete it. Start over.

No exceptions:
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete

Implement fresh from tests. Period.

「参考として残しておこう」→ ダメ。「テストを書きながら調整しよう」→ ダメ。「見るだけ」→ ダメ。Delete means delete.

このエスカレーションの設計が巧みです。「テスト前にコードを書いてしまった」という事実に対して、LLM が使いそうな合理化を4段階で先回りして封殺しています。

合理化テーブル

TDD スキルにも、using-superpowers と同様の合理化テーブルがあります。11項目。

個人的に「なるほど」と思ったのは3行目。「テストを後で書いても同じでしょ？」に対して「テスト後書き = このコードは何をする？ テスト先書き = このコードは何をすべき？ 問いの方向が違う」という反論。これはLLMに限らず人間にも刺さります。

そしてこの一文で、「精神に従っている」系の合理化を丸ごと無効化しています。

Violating the letter of the rules is violating the spirit of the rules.

DOT 記法によるフローチャート

TDD の Red-Green-Refactor サイクルは Graphviz の DOT 記法で定義されています。

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test"];
    verify_red [label="Verify fails\ncorrectly"];
    green [label="GREEN\nMinimal code"];
    verify_green [label="Verify passes\nAll green"];
    refactor [label="REFACTOR\nClean up"];
    ...
}

obra 自身がブログで書いています。

dot is a graph and process notation that reads a little bit like ASCII art. As a slightly-formalized notation, dot is a little bit less ambiguous than prose. Claude is particularly good at following processes written in dot.

自然言語だと「テストが失敗することを確認してから実装に進む」の「確認してから」が曖昧になりがちですが、DOT記法なら判断ノードとして明示的に表現できます。superpowers 全体で8箇所に DOT フローチャートが使われていて、これは意図的な設計判断です。

ソクラテス式対話としての brainstorming

brainstorming/SKILL.md は、実装に入る前の設計フェーズを制御するスキルです。

冒頭に <HARD-GATE> が置かれています。

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and the
user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

設計なしにコードを書くことを物理的にブロックしています。「EVERY project regardless of perceived simplicity」がポイントで、「これは簡単だから設計不要」という合理化への先手です。

実際、こう書いてあります。

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. “Simple” projects are where unexamined assumptions cause the most wasted work.

TODOリストも、ユーティリティ関数1つも、設定変更も。全部ブレストを通す。シンプルなプロジェクトこそ、検証されていない思い込みが最大の手戻りを生むからです。

9ステップの対話フロー

brainstorming は9ステップのチェックリストで進行します。

1. プロジェクトコンテキスト探索
2. ビジュアルコンパニオン提案（v5 の新機能）
3. 質問は1つずつ
4. 2-3のアプローチ提案（トレードオフ付き）
5. セクションごとのデザイン提示・承認
6. 設計ドキュメント作成・コミット
7. Spec レビューループ（サブエージェントによる自動レビュー、最大3回）
8. ユーザーによるスペック承認ゲート
9. writing-plans スキルへの遷移

ステップ3の「質問は1つずつ」がソクラテス式のキモです。LLM は放っておくと質問を5個くらい一気に投げてきますが、それだとユーザーが圧倒されてしまう。1メッセージ1質問、可能なら選択肢形式で。

出口の制約

brainstorming の出口は writing-plans スキルのみに限定されています。

The terminal state is invoking writing-plans. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill.

brainstorming → writing-plans → subagent-driven-development（or executing-plans）→ finishing-a-development-branch

このパイプラインが構造的に強制されています。brainstorming から直接実装スキルに飛ぶことはできません。「設計→計画→実装」の順序を、スキル間の遷移制約で担保しているわけです。

信頼するな、検証しろ

subagent-driven-development/SKILL.md は、サブエージェントを使った開発ワークフローを定義しています。

コアの原則はこちら。

Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

コンテキスト分離

サブエージェントは親セッションのコンテキストを一切継承しません。親（コーディネーター）がタスクのフルテキスト + 必要なコンテキストを精密に構築して渡します。

これは「コンテキスト汚染（context pollution）」を防ぐ設計です。長いセッションで蓄積された無関係な情報がサブエージェントの判断を歪めないようにしています。

2段階レビュー

実装が終わると、2つの独立したレビューが走ります。

1. Spec Compliance Review: コードが仕様を正確に満たしているか
2. Code Quality Review: 実装の品質が十分か

この順序は固定です。spec が通るまで code quality review には進めません。

Spec Reviewer のプロンプトテンプレート（spec-reviewer-prompt.md）に、こんな一節があります。

## CRITICAL: Do Not Trust the Report
The implementer finished suspiciously quickly. Their report may be incomplete,
inaccurate, or optimistic. You MUST verify everything independently.

「報告を信用するな。コードを読め。」——実装者の報告は不完全かもしれないし、楽観的かもしれない。独立して検証しろ、と。

これはソフトウェア開発のコードレビューそのものですが、AI同士のやり取りでも同じ原則が必要というのは面白いです。

ステータスハンドリング

実装者サブエージェントは4種類のステータスを返します。

• DONE: spec review へ進む
• DONE_WITH_CONCERNS: 懸念事項を読んで判断してからレビューへ
• NEEDS_CONTEXT: 足りない情報を追加して再 dispatch
• BLOCKED: ブロッカーを評価（コンテキスト問題 / モデル能力問題 / タスク分割 / 計画修正）

BLOCKED の場合の評価軸が具体的なのがいいですね。「ブロックされたから失敗」ではなく、原因を切り分けて次のアクションを決める構造になっています。

モデル選択ガイド

コスト最適化のためのモデル選択ガイドもあります。

• 機械的な実装（1-2ファイル、明確なスペック）→ 安価な高速モデル
• 統合・判断タスク（複数ファイル連携）→ 標準モデル
• 設計・レビュータスク → 最高性能モデル

全部 Opus で回す必要はないわけです。タスクの性質に応じてモデルを使い分けることで、品質を維持しながらコストを抑えられます。

スキル横断で見える設計パターン

ここまで個別のスキルを読んできましたが、スキル横断で見ると繰り返し使われている設計パターンが浮かび上がります。7つ整理しました。

1. Iron Law パターン

絶対的なルールを1行で宣言する。

• TDD: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
• debugging: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
• writing-skills: NO SKILL WITHOUT A FAILING TEST FIRST

書き方が統一されていて、NO X WITHOUT Y FIRST のフォーマットです。

2. Rationalization Table パターン

エージェントが使いそうな合理化フレーズを事前に列挙して封殺する。

• using-superpowers: Red Flags テーブル（12項目）
• TDD: Common Rationalizations テーブル（11項目）
• debugging: 独自の合理化テーブル

これらは「想像で書いた」ものではなく、実際に LLM がスキルを破った際の出力を逐語記録して作成されたものです。writing-skills の「TDD for Skills」セクションに、このプロセスが文書化されています。

3. HARD-GATE パターン

XMLタグで「絶対に超えてはならない境界」を宣言する。

<HARD-GATE>
Do NOT invoke any implementation skill...
</HARD-GATE>

brainstorming で使われています。LLM は XML タグの境界を認識しやすいので、自然言語で「〜しないでください」と書くより効果的です。

4. Graphviz Flow パターン

判断分岐を DOT 記法で明示的に記述する。superpowers 全体で8箇所に使われています。

5. Two-Stage Review パターン

spec 準拠 → コード品質の2段階レビュー。subagent-driven-development で使われています。

6. Subagent Isolation パターン

タスクごとに新しいサブエージェントを起動して、コンテキスト汚染を防ぐ。

7. Progressive Disclosure パターン

スキルの情報を段階的に読み込む設計。セッション開始時は全スキルの name/description だけがロードされ、実際に使うスキルの SKILL.md 本文はオンデマンドで読み込まれます。使わないスキルのトークンコストはゼロです。

Cialdini の説得原理

これらのパターンの背景には、心理学の知見があります。superpowers は writing-skills/persuasion-principles.md で、Cialdini の7つの説得原理のうち5つを LLM に明示的に適用しています。

• Authority（権威）: 「YOU MUST」「No exceptions」→ 意思決定疲労を排除
• Commitment（一貫性）: スキル使用のアナウンス義務化 → 宣言したら従う
• Scarcity（希少性）: 「Before proceeding」→ 先送りを防止
• Social Proof（社会的証明）: 「Every time」「Always」→ 例外を作らせない
• Unity（一体感）: 「our codebase」「we’re colleagues」→ 協調関係の構築

superpowers が引用する Meincke et al. (2025) “Call Me A Jerk: Persuading AI to Comply with Objectionable Requests” (University of Pennsylvania) の研究では、N=28,000 の AI 会話で説得テクニックの適用によりコンプライアンス率が 33% → 72% に向上したと報告されています。

残り2つの原理（Reciprocity, Liking）は「ほぼ使うべきでない」「常に避けるべき」と明記されていて、使い分けまで文書化されているのは律儀です。

CSO（Claude Search Optimization）

writing-skills/SKILL.md で定義されている、スキル発見の最適化手法です。SEO のアナロジーですね。

最も重要な発見は「description の罠」です。

# BAD: ワークフロー要約が入っている → Claude がスキル本文を読まない
description: Use when executing plans - dispatches subagent per task with code review between tasks

# GOOD: トリガー条件のみ → Claude が本文を正しく読む
description: Use when executing implementation plans with independent tasks in the current session

BAD の方では、Claude は description を読んだだけで「サブエージェントを使ってレビュー付きで実行すればいいんだな」と判断し、スキル本文の2段階レビューフローを読みません。結果、レビューが1回しか行われなかったりします。

description は「いつ使うか」だけ書いて、「何をするか」は書かない。これが CSO の鉄則です。自作スキルを書く際に最初に知っておくべきルールだと思います。

独自レビュー

ここまで読んできて感じた、よくできている点と惜しい点をまとめます。

よくできている点

合理化防止の多層防御がとにかく徹底している。 Iron Law で宣言し、Rationalization Table で合理化フレーズを封殺し、Red Flags で自己チェックを促し、HARD-GATE で物理的にブロックし、Persuasion Principles で心理学的に強化する。ここまで体系的にやっているフレームワークは他にあまり見かけません。

「お願い」ではなく「アーキテクチャ」で規律を実現している。 CLAUDE.md に「テストを先に書いてください」と書くのと、superpowers の TDD スキルは根本的に違います。前者は「お願い」で、LLM はプレッシャー下で合理化してスキップする。後者は合理化パターン自体を事前に潰す「構造的強制」です。

DOT 記法によるプロセス定義は実用的。 曖昧さの排除という観点で、自然言語より DOT の方が LLM の追従精度が高いという知見は、自作スキルにすぐ活かせます。

スキル自体を TDD で開発する発想。 「スキルなしで LLM がどう合理化するか」をベースラインとして記録し、スキルを書いて改善を確認する。メタ的ですが、品質保証の仕組みとして筋が通っています。

Progressive Disclosure によるトークン効率。 14スキル全部を常時コンテキストに入れるのではなく、name/description だけプリロードしてオンデマンドで読み込む設計。使わないスキルのコストがゼロなのは大きいです。

惜しい点

フロントマターフィールドの文書化が追いついていない。 Issue #882（執筆時点でオープン）で指摘されている通り、writing-skills は「name と description の2フィールドのみサポート」と教えますが、実際の Claude Code は effort, model, context, hooks など 11フィールドをサポートしています。superpowers が意図的に2フィールドに限定しているのはマルチプラットフォーム互換性のためですが、自作スキル開発者がこれを知らないと高度な機能を見逃します。

brainstorming のコンテキスト活用に改善の余地がある。 Issue #849（執筆時点でオープン）で報告されているように、プロジェクトに豊富なコンテキスト（CLAUDE.md 等）があっても、brainstorming スキルが汎用的な質問をしてしまう場合があります。ソクラテス式対話のテンプレート性が少し強すぎるのかもしれません。

writing-plans の強制度がまだ揺れている。 v5.0.0 で subagent-driven-development の使用を必須にしたのですが、v5.0.5 でユーザー選択に戻しています。「どこまで強制するか」のバランスは、まだ調整中のようです。

スキルのテスト自動化が限定的。 サブエージェントによるシナリオテストは用意されていますが、CI/CD パイプラインでの定量的な自動評価は未整備です。Anthropic 公式の skill-creator が提供する eval ベースのアプローチと比べると、ここは差があります。

CLAUDE.md や Cursor Rules との違い

最後に位置づけの整理を。

CLAUDE.md に直接ルールを書くのと、superpowers のスキルシステムには根本的な違いがあります。CLAUDE.md は「お願い」レベルのプロンプトインジェクション。superpowers は合理化パターンを封じる「構造的強制」。

ただ、superpowers は CLAUDE.md を置き換えるものではなく、上に乗るレイヤーです。プロジェクト固有のルール（コーディング規約、使用ライブラリの制約）は CLAUDE.md に書き、汎用的な開発ワークフロー（TDD、ブレスト、デバッグ）は superpowers に任せる。この使い分けが superpowers 自身の設計で明示されています。

まとめ

superpowers の SKILL.md を全部読んで分かったのは、これが「便利なプロンプト集」ではなく、LLMにルールを守らせるための設計知見の体系だということです。

自作スキルを書くなら、まず以下を意識するとよさそうです。

• description は「Use when…」で始め、ワークフローを含めない（CSOの鉄則）
• LLM が破りそうなルールは、合理化テーブルで塞ぐ
• プロセスフローは DOT 記法で定義する（曖昧さの排除）
• <HARD-GATE> や <EXTREMELY-IMPORTANT> の XML タグで構造的に強制する
• スキルのテストは「スキルなしで失敗する」ベースラインから始める

全スキルの SKILL.md は obra/superpowers の skills/ ディレクトリで読めます。この記事で引用したファイルへのリンクを置いておきます。

• using-superpowers/SKILL.md
• test-driven-development/SKILL.md
• brainstorming/SKILL.md
• subagent-driven-development/SKILL.md
• systematic-debugging/SKILL.md
• writing-skills/SKILL.md
• hooks/hooks.json
• hooks/session-start

自作スキルを始めるなら、writing-skills/SKILL.md を読んで TDD プロセスを実践するのが最も確実なスタート地点です。