using-superpowers

Vue d’ensemble

À quoi sert la skill using-superpowers

La skill using-superpowers sert de point de départ aux conversations pour les agents IA. Elle définit la manière dont un agent doit :

• Décider quand invoquer des skills (et rendre cela obligatoire lorsque c’est pertinent)
• Hiérarchiser les instructions entre les requêtes utilisateur, les skills superpowers et le comportement système par défaut
• Accéder aux skills et les activer correctement sur différentes plateformes comme Claude Code et Gemini CLI
• Traduire les noms d’outils "superpowers" standard en équivalents spécifiques à chaque plateforme

Cette skill est conçue pour être utilisée au début de toute nouvelle conversation ou tâche. Elle établit un contrat partagé : dès qu’il existe la moindre chance qu’une skill soit pertinente, l’agent doit l’invoquer avant de répondre, y compris avant de poser des questions de clarification.

Pour qui using-superpowers est-il conçu

Utilisez la skill using-superpowers si vous êtes :

• Un développeur qui configure Claude Code, Gemini CLI ou des environnements similaires
• Responsable d’un espace de travail multi-skills, multi-agents et en quête de comportement cohérent
• Utilisateur du dépôt obra/superpowers comme bibliothèque standard de skills
• Concepteur de workflows internes où les agents doivent suivre des procédures documentées et utiliser les bons outils

Elle est particulièrement utile dans les projets d’envergure où ignorer une skill pertinente (par exemple une skill de revue de code ou de planification) peut entraîner des résultats incohérents ou des contrôles de sécurité manqués.

Problèmes que cette skill résout

La skill using-superpowers traite plusieurs problèmes fréquents dans les workflows basés sur des agents :

• Des agents qui répondent "à l’instinct" au lieu de vérifier les skills disponibles
• Des doutes sur le caractère autoritatif des instructions utilisateur vs celles des skills
• Une mauvaise utilisation des outils (par exemple lire directement les fichiers d’une skill au lieu d’utiliser l’outil Skill)
• Les différences de plateforme entre Claude Code, Gemini CLI et d’autres environnements

En installant et activant using-superpowers, vous réduisez ces incohérences et clarifiez la façon dont les skills doivent être découvertes et utilisées.

Quand using-superpowers est (ou n’est pas) adapté

Bon cas d’usage :

• Vous dépendez de plusieurs skills qui doivent être suivies de façon cohérente
• Vous voulez que les agents cherchent systématiquement des skills pertinentes avant de continuer
• Vous opérez sur plusieurs plateformes et avez besoin d’un mapping entre les noms d’outils
• Vous construisez ou maintenez une bibliothèque de skills de type superpowers

Moins adapté lorsque :

• Vous êtes un sous-agent à usage unique déclenché pour une tâche très ciblée (la skill précise que les sous-agents doivent l’ignorer)
• Vous avez un setup minimal sans skills supplémentaires ni intégrations d’outils
• Vous recherchez un comportement entièrement libre et exploratoire, sans règles strictes sur le moment où invoquer des skills

---

Mode d’emploi

1. Installer la skill using-superpowers

Installez using-superpowers depuis le dépôt obra/superpowers à l’aide de Skills CLI :

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

Cette commande importe la définition de la skill using-superpowers et sa documentation de référence dans votre environnement de skills.

Après l’installation, vous devriez au minimum voir ces fichiers pour cette skill :

• SKILL.md — comportement principal et priorité des instructions
• references/codex-tools.md — mapping des outils pour les environnements de type Codex
• references/gemini-tools.md — mapping des outils pour Gemini CLI

2. Comprendre la règle des sous-agents

La skill inclut un garde-fou pour les sous-agents :

• Si un agent est déclenché comme sous-agent pour accomplir une tâche spécifique, il doit ignorer cette skill.
• Cela permet aux sous-agents de rester concentrés sur leur tâche et évite de réinitialiser le comportement global des skills.

En tant que concepteur de workflow, vous devez :

• Veiller à ce que votre agent principal invoque using-superpowers au début d’une conversation
• Configurer les sous-agents pour qu’ils ne relancent pas cette skill lorsqu’ils sont créés pour une mission dédiée

3. Suivre le modèle de priorité des instructions

using-superpowers définit une hiérarchie claire pour les instructions :

1. Instructions utilisateur — priorité maximale
   • Requêtes directes de l’utilisateur
   • Fichiers spécifiques au projet comme CLAUDE.md, GEMINI.md, AGENTS.md
2. Skills superpowers — y compris using-superpowers et les autres skills de la bibliothèque
3. Prompt système par défaut / paramètres par défaut du modèle — priorité la plus basse

Concrètement, cela signifie :

• Si CLAUDE.md ou GEMINI.md est en conflit avec une skill, le fichier de l’utilisateur prévaut.
• Les skills superpowers peuvent surcharger le comportement par défaut du modèle uniquement si elles ne contredisent pas les instructions utilisateur.
• Le prompt système par défaut comble les trous lorsque ni les instructions utilisateur ni les skills ne s’appliquent.

Lors de la configuration de votre environnement, assurez-vous que ces sources sont toutes accessibles et que votre agent principal connaît cet ordre de priorité.

4. Faire respecter l’invocation obligatoire des skills

Une règle centrale de using-superpowers est que l’invocation des skills est obligatoire dès qu’elle est pertinente :

• S’il existe ne serait-ce qu’1 % de chance qu’une skill s’applique à la tâche en cours, l’agent doit l’invoquer.
• Les agents ne doivent ni répondre ni poser de questions de clarification avant d’avoir invoqué la skill pertinente lorsqu’elle pourrait s’appliquer.

Cette règle vise à :

• Empêcher les agents d’"ignorer" des skills qui contiennent des logiques de sécurité ou de workflow importantes
• Encourager une approche skills-first, où l’agent cherche et utilise la bonne skill avant d’improviser

En tant que développeur, vous pouvez :

• Considérer cela comme une partie de votre politique organisationnelle pour les agents
• Expliquer aux utilisateurs que les premières étapes d’une conversation peuvent inclure l’invocation de skills avant la réponse

5. Utiliser la bonne méthode d’accès aux skills selon la plateforme

La skill using-superpowers définit la façon d’accéder aux skills sur différentes plateformes.

Claude Code

• Utilisez l’outil Skill pour invoquer les skills.
• Lorsqu’une skill est invoquée, son contenu est chargé et présenté à l’agent — l’agent doit la suivre directement.
• L’agent ne doit pas utiliser l’outil Read pour ouvrir les fichiers de skills ; il doit s’appuyer sur l’outil Skill pour cela.

Gemini CLI

• Les skills sont activées via l’outil activate_skill.
• Gemini charge les métadonnées des skills au démarrage de la session et active le contenu complet à la demande.
• Lorsqu’une skill est activée, l’agent doit suivre les instructions fournies par cette skill.

Autres environnements

Pour les environnements au-delà de Claude Code et Gemini CLI :

• Consultez la documentation de votre plateforme pour savoir comment elle gère l’activation des skills ou les workflows basés sur des outils.
• Utilisez les références fournies dans ce dépôt comme guide pour mapper les noms d’outils "superpowers" génériques vers les équivalents de votre plateforme.

6. Mapper les outils vers les environnements de type Codex

Si vous utilisez un Codex CLI ou un environnement similaire, lisez :

• references/codex-tools.md

Concepts clés de cette référence :

• Les skills utilisent par défaut les noms d’outils de Claude Code.
• Le fichier fournit une table de correspondance entre les outils superpowers et leurs équivalents Codex, notamment :
  • Task → spawn_agent
  • Appels multiples à Task → appels multiples à spawn_agent
  • Résultat d’une tâche → wait
  • Fin de tâche → close_agent
  • TodoWrite → update_plan
  • Skill → gestion native des skills
  • Read / Write / Edit / Bash → outils fichiers et shell correspondants dans Codex

Cette référence documente également :

• Comment activer le support multi-agents dans Codex en ajoutant dans ~/.codex/config.toml :

[features]
multi_agent = true

• Comment gérer la délégation à des agents nommés lorsque Codex ne dispose pas d’un registre d’agents nommés, notamment en lisant un fichier de prompt (comme agents/code-reviewer.md), en remplissant les placeholders, puis en lançant un agent worker avec ce prompt.

7. Mapper les outils vers Gemini CLI

Pour utiliser Gemini CLI, lisez :

• references/gemini-tools.md

Cette référence explique comment les outils superpowers standard se mapent vers les outils Gemini CLI, par exemple :

• 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

Elle précise également :

• Gemini CLI ne supporte pas les sous-agents — il n’y a pas d’équivalent à l’outil Task.
• Les skills qui dépendent de sous-agents (comme subagent-driven-development ou dispatching-parallel-agents) se replient sur une exécution en session unique via d’autres skills de planification (telles que executing-plans).
• Gemini CLI inclut des outils supplémentaires sans équivalent direct dans Claude Code, comme list_directory, save_memory, ask_user, tracker_create_task, et enter_plan_mode / exit_plan_mode.

8. Ordre de lecture recommandé

Pour tirer le meilleur parti de using-superpowers dans un nouvel espace de travail :

1. Commencez par SKILL.md
   • Comprenez la priorité des instructions et les règles d’invocation obligatoire des skills.
2. Ouvrez references/codex-tools.md (si vous utilisez Codex ou un environnement similaire)
   • Configurez le support multi-agents et les mappings d’outils.
3. Ouvrez references/gemini-tools.md (si vous utilisez Gemini CLI)
   • Découvrez le mapping des outils et l’absence de support pour les sous-agents.

Vous pourrez ensuite adapter ces modèles à vos propres outils et fichiers de configuration.

---

FAQ

Comment installer la skill using-superpowers ?

Utilisez Skills CLI pour l’ajouter depuis le dépôt obra/superpowers :

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

Une fois installée, ouvrez SKILL.md pour les règles de base et le dossier references/ pour les mappings d’outils spécifiques à chaque plateforme.

Quand un agent doit-il exécuter using-superpowers ?

La skill using-superpowers est conçue pour être exécutée au début d’une conversation ou d’une tâche par votre agent principal. Elle doit être utilisée lorsqu’un agent s’apprête à :

• Commencer à travailler sur un projet qui utilise des skills superpowers
• Décider quelles skills utiliser pour une nouvelle demande
• Opérer dans un environnement de développement multi-outils et multi-plateformes

Les sous-agents déclenchés pour des tâches ciblées doivent ignorer cette skill et simplement suivre les prompts ou instructions qui leur sont passés.

Est-ce que using-superpowers remplace les instructions utilisateur ?

Non. La skill indique explicitement que les instructions utilisateur priment toujours. L’ordre de priorité est :

1. Instructions utilisateur (y compris CLAUDE.md, GEMINI.md, AGENTS.md et les requêtes directes)
2. Skills superpowers comme using-superpowers
3. Comportement du prompt système par défaut

En cas de conflit entre une instruction utilisateur et une skill, l’agent doit suivre l’instruction de l’utilisateur.

Que signifie "invocation obligatoire des skills" en pratique ?

L’invocation obligatoire des skills signifie :

• S’il existe la moindre chance réaliste qu’une skill s’applique à la tâche en cours, l’agent doit l’invoquer.
• L’agent ne doit pas commencer par répondre ou poser des questions de clarification lorsqu’une skill pertinente pourrait exister.

Cela permet de garantir que :

• Les skills liées à la sécurité et aux workflows sont appliquées de manière systématique
• Les agents s’appuient sur des procédures éprouvées plutôt que d’improviser

Quel impact using-superpowers a-t-il sur Claude Code ?

Dans Claude Code :

• Les agents doivent utiliser l’outil Skill pour charger et suivre les skills, y compris using-superpowers.
• Ils ne doivent pas utiliser l’outil Read pour ouvrir directement les fichiers de skills.
• Une fois using-superpowers active, l’agent suit ses lignes directrices pour la priorité des instructions et l’invocation des skills.

Vous pouvez combiner cette skill avec d’autres skills du même dépôt pour bâtir un workflow de développement robuste et piloté par les skills.

Comment using-superpowers fonctionne-t-il avec Gemini CLI ?

Avec Gemini CLI :

• Les skills sont activées via l’outil activate_skill.
• using-superpowers précise que Gemini charge les métadonnées des skills au démarrage de la session et active le contenu complet à la demande.
• Les noms d’outils mentionnés dans les skills superpowers sont mappés vers les outils Gemini CLI dans references/gemini-tools.md.

Gardez en tête que Gemini CLI ne supporte pas les sous-agents ; les skills qui reposent sur la délégation à des sous-agents basculent automatiquement vers des schémas d’exécution en session unique.

Puis-je utiliser using-superpowers sur d’autres plateformes d’agents ?

Oui, tant que votre plateforme prend en charge le concept de skills ou d’outils :

• Utilisez SKILL.md comme source de vérité pour le comportement et la priorité des instructions.
• Consultez references/codex-tools.md et references/gemini-tools.md comme exemples de mapping des noms d’outils superpowers vers votre plateforme.
• Mettez en place une couche de mapping similaire pour aligner les outils de votre plateforme sur les attentes de la skill.

Vous devrez peut-être adapter ou étendre ces mappings selon les capacités de votre plateforme.

Quels fichiers dois-je lire en premier après l’installation de la skill ?

Pour une mise en route rapide et pragmatique :

1. SKILL.md — comportement de base, priorité des instructions et règle d’invocation obligatoire des skills.
2. references/codex-tools.md — si vous utilisez Codex ou un environnement de type Codex.
3. references/gemini-tools.md — si vous utilisez Gemini CLI.

À partir de là, vous pouvez explorer les autres skills du dépôt obra/superpowers pour construire un workflow plus complet.

using-superpowers suffit-il à lui seul ?

using-superpowers fournit la fondation de la découverte et de l’application des skills, mais il est bien plus puissant lorsqu’il est combiné avec d’autres skills du même écosystème (pour la planification, la revue de code, les tests, etc.).

Utilisez-le comme première couche de configuration de vos agents, puis ajoutez des skills spécifiques à votre domaine en fonction des besoins de votre projet.