using-superpowers

Übersicht

Was das using-superpowers Skill macht

Das using-superpowers Skill ist ein Conversation-Bootstrapper für AI Agents. Es legt fest, wie ein Agent:

• Entscheidet, wann Skills auszuführen sind (und dies bei Relevanz nicht optional ist)
• Instruktionen priorisiert – zwischen User Prompts, Superpowers Skills und dem Standard-Systemverhalten
• Skills korrekt aufruft und nutzt auf verschiedenen Plattformen wie Claude Code und Gemini CLI
• Standardisierte „superpowers“-Tool-Namen in plattformspezifische Entsprechungen übersetzt

Dieses Skill ist dafür gedacht, zu Beginn jeder neuen Unterhaltung oder Aufgabe eingesetzt zu werden. Es etabliert einen gemeinsamen Vertrag: Sobald es auch nur eine geringe Chance gibt, dass ein Skill relevant ist, muss der Agent ihn vor der Antwort aufrufen – auch bevor Rückfragen gestellt werden.

Für wen using-superpowers gedacht ist

Nutze das using-superpowers Skill, wenn du:

• Developer bist und Claude Code, Gemini CLI oder ähnliche Umgebungen konfigurierst
• Einen Workspace mit mehreren Skills und Agents betreibst und konsistentes Verhalten sicherstellen möchtest
• Das obra/superpowers Repository als Standardbibliothek für Skills verwendest
• Interne Workflows aufbaust, in denen Agents dokumentierten Verfahren folgen und die richtigen Tools verwenden müssen

Besonders wertvoll ist es in größeren Projekten, in denen das Übersehen eines relevanten Skills (z. B. für Code Review oder Planning) zu inkonsistenten Ergebnissen oder fehlenden Safety Checks führen kann.

Probleme, die dieses Skill löst

Das using-superpowers Skill adressiert mehrere typische Probleme in Agent-Workflows:

• Agents antworten aus dem Bauch heraus, statt verfügbare Skills zu prüfen
• Unklarheit, ob User-Instruktionen oder Skills maßgeblich sind
• Falsche Tool-Nutzung (z. B. Skill-Dateien direkt lesen statt das Skill Tool zu verwenden)
• Plattformunterschiede zwischen Claude Code, Gemini CLI und anderen Umgebungen

Durch Installation und Aktivierung von using-superpowers reduzierst du diese Inkonsistenzen und machst klar, wie Skills gefunden und eingesetzt werden sollen.

Wann using-superpowers sinnvoll ist – und wann nicht

Gut geeignet, wenn:

• Du dich auf mehrere Skills verlässt, denen in konsistenter Weise gefolgt werden muss
• Du möchtest, dass Agents immer nach relevanten Skills suchen, bevor sie fortfahren
• Du plattformübergreifend arbeitest und eine Zuordnung zwischen Tool-Namen benötigst
• Du eine Superpowers-Style-Skill-Bibliothek aufbaust oder pflegst

Weniger geeignet, wenn:

• Du ein Single-Use-Subagent bist, der für eine eng umrissene Aufgabe gestartet wird (das Skill sagt explizit, dass Subagents es überspringen sollen)
• Du nur ein Minimalsetup ohne zusätzliche Skills oder Tool-Integrationen betreibst
• Du komplett freie, explorative Agent-Verläufe ohne strikte Regeln zum Skill-Einsatz möchtest

---

Verwendung

1. using-superpowers Skill installieren

Installiere using-superpowers aus dem obra/superpowers Repository mit der Skills CLI:

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

Damit werden die using-superpowers Skill-Definition und die dazugehörigen Referenzdokumente in deine Skills-Umgebung geladen.

Nach der Installation solltest du mindestens diese Dateien für dieses Skill sehen:

• SKILL.md — zentrales Verhalten und Instruktions-Priorität
• references/codex-tools.md — Tool-Mapping für Codex-ähnliche Umgebungen
• references/gemini-tools.md — Tool-Mapping für Gemini CLI

2. Die Subagent-Regel verstehen

Das Skill enthält einen Subagent Guard:

• Wird ein Agent als Subagent für eine konkrete Aufgabe gestartet, soll er dieses Skill überspringen.
• So bleiben Subagents auf ihre Aufgabe fokussiert und initialisieren das globale Skill-Verhalten nicht erneut.

Als Workflow-Designer solltest du:

• Sicherstellen, dass dein Primary Agent using-superpowers zu Beginn einer Unterhaltung ausführt
• Subagents so konfigurieren, dass sie dieses Skill nicht erneut laufen lassen, wenn sie für einen dedizierten Job gespawnt werden

3. Dem Instruktions-Prioritätsmodell folgen

using-superpowers definiert eine klare Hierarchie für Instruktionen:

1. User Instructions — höchste Priorität
   • Direkte User Prompts
   • Projektspezifische Dateien wie CLAUDE.md, GEMINI.md, AGENTS.md
2. Superpowers Skills — inkl. using-superpowers und anderer Skills aus der Bibliothek
3. Default System Prompt / Model Defaults — niedrigste Priorität

Praktisch bedeutet das:

• Wenn CLAUDE.md oder GEMINI.md einem Skill widerspricht, gewinnt die User-Datei.
• Superpowers Skills dürfen Standard-Model-Verhalten nur überschreiben, wenn sie nicht im Widerspruch zu User-Instruktionen stehen.
• Der Default System Prompt füllt Lücken, wenn weder User-Instruktionen noch Skills greifen.

Stelle bei der Konfiguration deiner Umgebung sicher, dass diese Quellen alle sichtbar sind und dein Primary Agent diese Reihenfolge kennt.

4. Pflicht zum Skill-Aufruf durchsetzen

Eine Kernregel von using-superpowers ist, dass der Skill-Aufruf verpflichtend ist, wenn er relevant sein könnte:

• Gibt es auch nur eine 1 % Chance, dass ein Skill auf die aktuelle Aufgabe zutrifft, muss der Agent ihn aufrufen.
• Agents sollen nicht antworten oder Rückfragen stellen, bevor sie einen möglicherweise relevanten Skill ausgeführt haben.

Diese Regel soll:

• Verhindern, dass Agents Skills „überspringen“, die wichtige Safety- oder Workflow-Logik enthalten
• Einen Skills-first Ansatz fördern, bei dem der Agent zuerst nach dem passenden Skill sucht und ihn nutzt, bevor er improvisiert

Als Developer kannst du:

• Dies als Teil deiner organisationalen Agent Policy definieren
• Usern erklären, dass der Agent in frühen Gesprächsphasen eventuell Skills ausführt, bevor er antwortet

5. Pro Plattform den richtigen Skill-Zugriff nutzen

Das using-superpowers Skill legt fest, wie Skills auf verschiedenen Plattformen aufgerufen werden.

Claude Code

• Verwende das Skill Tool, um Skills aufzurufen.
• Wenn ein Skill aufgerufen wird, wird sein Inhalt geladen und dem Agent präsentiert – der Agent soll den Skill dann direkt befolgen.
• Der Agent soll nicht das Read Tool verwenden, um Skill-Dateien zu öffnen, sondern sich hierfür auf das Skill Tool verlassen.

Gemini CLI

• Skills werden über das activate_skill Tool aktiviert.
• Gemini lädt Skill-Metadaten zu Beginn einer Session und aktiviert den vollständigen Inhalt on demand.
• Ist ein Skill aktiviert, soll der Agent den darin definierten Instruktionen folgen.

Andere Umgebungen

Für Umgebungen jenseits von Claude Code und Gemini CLI gilt:

• Konsultiere die Dokumentation deiner Plattform, wie sie Skill-Aktivierung oder Tool-basierte Workflows umsetzt.
• Nutze die Referenzen in diesem Repository als Vorlage, um generische „superpowers“-Tool-Namen auf die Entsprechungen deiner Plattform abzubilden.

6. Tools auf Codex-Style-Umgebungen abbilden

Wenn du eine Codex CLI oder eine ähnliche Umgebung verwendest, lies:

• references/codex-tools.md

Wichtige Konzepte aus dieser Referenz:

• Skills verwenden standardmäßig Claude Code Tool-Namen.
• Die Datei stellt eine Mapping-Tabelle zwischen Superpowers Tools und Codex-Entsprechungen bereit, u. a.:
  • Task → spawn_agent
  • Mehrere Task Aufrufe → mehrere spawn_agent Aufrufe
  • Task result → wait
  • Task completion → close_agent
  • TodoWrite → update_plan
  • Skill → native skills handling
  • Read / Write / Edit / Bash → entsprechende Codex File- und Shell-Tools

Außerdem wird beschrieben:

• Wie du Multi-Agent Support in Codex aktivierst, indem du in ~/.codex/config.toml ergänzst:

[features]
multi_agent = true

• Wie Named Agent Dispatch gehandhabt werden kann, wenn Codex kein Named Agent Registry besitzt – inkl. Lesen einer Prompt-Datei (z. B. agents/code-reviewer.md), Ausfüllen von Platzhaltern und Spawnen eines worker Agents mit diesem Prompt.

7. Tools auf Gemini CLI abbilden

Für die Nutzung mit Gemini CLI lies:

• references/gemini-tools.md

Diese Referenz erklärt, wie Standard-Superpowers-Tools auf Gemini CLI Tools gemappt werden, zum Beispiel:

• 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

Außerdem wird dort festgehalten:

• Gemini CLI unterstützt keine Subagents – es gibt kein Äquivalent zum Task Tool.
• Skills, die auf Subagents angewiesen sind (z. B. subagent-driven-development oder dispatching-parallel-agents), fallen auf Single-Session-Ausführung über andere Planning Skills (wie executing-plans) zurück.
• Gemini CLI bietet zusätzliche Tools ohne direktes Claude Code Pendant, etwa list_directory, save_memory, ask_user, tracker_create_task sowie enter_plan_mode / exit_plan_mode.

8. Empfohlene Lesereihenfolge

Um using-superpowers in einem neuen Workspace optimal zu nutzen:

1. Starte mit SKILL.md
   • Verstehe Instruktions-Priorität und Regeln zur verpflichtenden Skill-Ausführung.
2. Öffne references/codex-tools.md (wenn du Codex oder eine ähnliche Umgebung nutzt)
   • Konfiguriere Multi-Agent Support und Tool-Mappings.
3. Öffne references/gemini-tools.md (wenn du Gemini CLI nutzt)
   • Lerne das Tool-Mapping und die fehlende Subagent-Unterstützung kennen.

Anschließend kannst du diese Patterns auf deine eigenen Tools und Config-Files übertragen.

---

FAQ

Wie installiere ich das using-superpowers Skill?

Nutze die Skills CLI, um es aus dem obra/superpowers Repository hinzuzufügen:

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

Nach der Installation öffne SKILL.md für die Kernregeln und den Ordner references/ für plattformspezifische Tool-Mappings.

Wann sollte ein Agent using-superpowers ausführen?

Das using-superpowers Skill ist dafür gedacht, zu Beginn einer Unterhaltung oder Aufgabe vom Primary Agent ausgeführt zu werden. Es sollte eingesetzt werden, wenn ein Agent dabei ist:

• Mit der Arbeit in einem Projekt zu beginnen, das Superpowers Skills nutzt
• Zu entscheiden, welche Skills für eine neue Anfrage verwendet werden
• In einer Entwicklungsumgebung mit mehreren Tools und Plattformen zu arbeiten

Subagents, die für eng umrissene Tasks gestartet werden, sollen dieses Skill überspringen und stattdessen den ihnen übergebenen Prompts oder Instruktionen folgen.

Überschreibt using-superpowers User-Instruktionen?

Nein. Das Skill legt explizit fest, dass User-Instruktionen immer Vorrang haben. Die Priorität ist:

1. User Instructions (inkl. CLAUDE.md, GEMINI.md, AGENTS.md und direkte User Prompts)
2. Superpowers Skills wie using-superpowers
3. Standard-System-Prompt-Verhalten

Bei einem Konflikt zwischen User-Instruktionen und einem Skill muss der Agent den User-Instruktionen folgen.

Was bedeutet „mandatory skill invocation“ in der Praxis?

Mandatory Skill Invocation bedeutet:

• Gibt es irgendeine realistische Chance, dass ein Skill auf die aktuelle Aufgabe passt, muss der Agent ihn aufrufen.
• Der Agent soll nicht zuerst antworten oder Rückfragen stellen, wenn es einen relevanten Skill geben könnte.

Das hilft sicherzustellen, dass:

• Safety- und Workflow-Skills konsequent angewendet werden
• Agents auf erprobte Verfahren zurückgreifen, statt zu improvisieren

Wie wirkt sich using-superpowers auf Claude Code aus?

In Claude Code gilt:

• Agents sollen das Skill Tool nutzen, um Skills – inklusive using-superpowers – zu laden und zu befolgen.
• Sie sollen nicht das Read Tool verwenden, um Skill-Dateien direkt zu öffnen.
• Sobald using-superpowers aktiv ist, folgt der Agent dessen Richtlinien zu Instruktions-Priorität und Skill-Aufruf.

Du kannst das mit weiteren Skills aus demselben Repository kombinieren, um einen robusten, Skill-getriebenen Development-Workflow aufzubauen.

Wie funktioniert using-superpowers mit Gemini CLI?

Mit Gemini CLI gilt:

• Skills werden über das activate_skill Tool aktiviert.
• using-superpowers beschreibt, dass Gemini Skill-Metadaten zum Session-Start lädt und den vollständigen Inhalt bei Bedarf aktiviert.
• Die in Superpowers Skills referenzierten Tool-Namen werden in references/gemini-tools.md auf Gemini CLI Tools gemappt.

Beachte, dass Gemini CLI keine Subagents unterstützt; Skills, die Subagent Dispatch benötigen, fallen automatisch auf Single-Session-Ausführungsmuster zurück.

Kann ich using-superpowers auf anderen Agent-Plattformen nutzen?

Ja, solange deine Plattform das Konzept von Skills oder Tools unterstützt:

• Nutze SKILL.md als Single Source of Truth für Verhalten und Instruktions-Priorität.
• Sieh dir references/codex-tools.md und references/gemini-tools.md als Beispiele an, wie Superpowers Tool-Namen auf deine Plattform gemappt werden können.
• Implementiere eine ähnliche Mapping-Schicht, damit die Tools deiner Plattform zu den Erwartungen des Skills passen.

Je nach Fähigkeiten deiner Plattform musst du das Mapping möglicherweise anpassen oder erweitern.

Welche Dateien sollte ich nach der Installation zuerst lesen?

Für ein schnelles, praxisnahes Setup:

1. SKILL.md — Kernverhalten, Instruktions-Priorität und Regel zur verpflichtenden Skill-Ausführung.
2. references/codex-tools.md — wenn du Codex oder eine Codex-ähnliche Umgebung nutzt.
3. references/gemini-tools.md — wenn du Gemini CLI einsetzt.

Von dort kannst du weitere Skills im obra/superpowers Repository erkunden, um deinen Workflow auszubauen.

Reicht using-superpowers alleine aus?

using-superpowers legt das Fundament dafür, wie Skills gefunden und angewendet werden, ist aber am wirkungsvollsten im Zusammenspiel mit anderen Skills aus demselben Ökosystem (für Planning, Code Review, Testing usw.).

Nutze es als erste Schicht deiner Agent-Konfiguration und ergänze dann projektspezifische Skills je nach Bedarf deines Projekts.