using-superpowers

Descripción general

Qué hace la skill using-superpowers

La skill using-superpowers es un iniciador de conversaciones para agentes de IA. Define cómo debe un agente:

• Decidir cuándo invocar skills (y hacer que eso no sea opcional cuando proceda)
• Priorizar instrucciones entre las indicaciones del usuario, las skills de superpowers y el comportamiento de sistema por defecto
• Acceder y activar skills correctamente en distintas plataformas como Claude Code y Gemini CLI
• Traducir nombres estándar de herramientas "superpowers" a sus equivalentes específicos por plataforma

Esta skill está pensada para usarse al comienzo de cualquier conversación o tarea nueva. Establece un contrato compartido: si existe aunque sea una pequeña posibilidad de que una skill aplique, el agente debe invocarla antes de responder, incluso antes de hacer preguntas de aclaración.

Para quién es using-superpowers

Utiliza la skill using-superpowers si eres:

• Un desarrollador que configura Claude Code, Gemini CLI u otros entornos similares
• Responsable de un workspace con múltiples skills y múltiples agentes y quieres un comportamiento coherente
• Usuario del repositorio obra/superpowers como biblioteca estándar de skills
• Diseñador de flujos internos donde los agentes deban seguir procedimientos documentados y usar las herramientas correctas

Es especialmente útil en proyectos grandes donde pasar por alto una skill relevante (como una de revisión de código o planificación) puede provocar resultados inconsistentes o saltarse comprobaciones de seguridad.

Problemas que resuelve esta skill

La skill using-superpowers aborda varios problemas habituales en flujos de trabajo basados en agentes:

• Agentes que responden por intuición en lugar de revisar las skills disponibles
• Confusión sobre si son las instrucciones del usuario o las skills las que tienen prioridad
• Uso incorrecto de herramientas (por ejemplo, leer archivos de skills directamente en lugar de usar la herramienta Skill)
• Diferencias entre plataformas como Claude Code, Gemini CLI y otros entornos

Al instalar y activar using-superpowers, reduces estas inconsistencias y dejas claro cómo se deben descubrir y utilizar las skills.

Cuándo using-superpowers es, y cuándo no es, una buena opción

Buena opción cuando:

• Dependéis de varias skills que deben seguirse de forma coherente
• Quieres que los agentes siempre comprueben si hay skills relevantes antes de continuar
• Operas en múltiples plataformas y necesitas un mapeo entre nombres de herramientas
• Estás creando o manteniendo una biblioteca de skills al estilo superpowers

No es una buena opción cuando:

• Eres un subagente de un solo uso lanzado para una tarea muy acotada (la skill indica explícitamente que los subagentes deben omitirla)
• Solo tienes una configuración mínima sin skills adicionales ni integraciones de herramientas
• Buscas un comportamiento totalmente libre y exploratorio, sin reglas estrictas sobre cuándo invocar skills

---

Cómo usarla

1. Instalar la skill using-superpowers

Instala using-superpowers desde el repositorio obra/superpowers usando Skills CLI:

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

Esto trae la definición de la skill using-superpowers y su material de referencia a tu entorno de skills.

Tras la instalación, deberías ver al menos estos archivos para esta skill:

• SKILL.md — comportamiento principal y prioridad de instrucciones
• references/codex-tools.md — mapeo de herramientas para entornos tipo Codex
• references/gemini-tools.md — mapeo de herramientas para Gemini CLI

2. Entender la regla de subagente

La skill incluye una protección para subagentes:

• Si un agente se lanza como subagente para realizar una tarea específica, debe saltarse esta skill.
• Esto mantiene a los subagentes centrados en su tarea y evita re‑inicializar el comportamiento global de skills.

Como diseñador de flujos de trabajo, deberías:

• Asegurarte de que tu agente principal invoque using-superpowers al inicio de una conversación
• Configurar los subagentes para que no vuelvan a ejecutar esta skill cuando se creen para un trabajo específico

3. Seguir el modelo de prioridad de instrucciones

using-superpowers define una jerarquía clara para las instrucciones:

1. Instrucciones del usuario — máxima prioridad
   • Prompts directos del usuario
   • Archivos específicos del proyecto como CLAUDE.md, GEMINI.md, AGENTS.md
2. Skills de superpowers — incluyendo using-superpowers y otras skills de la biblioteca
3. Prompt de sistema por defecto / valores por defecto del modelo — menor prioridad

En la práctica, esto significa:

• Si CLAUDE.md o GEMINI.md entra en conflicto con una skill, gana el archivo del usuario.
• Las skills de superpowers pueden sobrescribir el comportamiento por defecto del modelo solo cuando no contradigan las instrucciones del usuario.
• El prompt de sistema por defecto rellena los huecos cuando no aplican ni las instrucciones del usuario ni las skills.

Al configurar tu entorno, asegúrate de que todas estas fuentes sean visibles y de que tu agente principal conozca este orden.

4. Aplicar la invocación obligatoria de skills

Una regla central de using-superpowers es que la invocación de skills es obligatoria cuando sea relevante:

• Si hay aunque sea un 1% de probabilidad de que una skill aplique a la tarea actual, el agente debe invocarla.
• Los agentes no deben responder ni hacer preguntas de aclaración antes de invocar la skill relevante cuando pudiera aplicar.

Esta regla está pensada para:

• Evitar que los agentes “se salten” skills que contienen lógica importante de seguridad o de flujo de trabajo
• Fomentar un enfoque centrado en las skills, en el que el agente busque y utilice la skill adecuada antes de improvisar

Como desarrollador, puedes:

• Tratar esto como parte de tu política organizativa para agentes
• Explicar a los usuarios que, en las primeras fases de la conversación, el agente puede invocar skills antes de responder

5. Usar el método correcto de acceso a skills según la plataforma

La skill using-superpowers define cómo acceder a las skills en distintas plataformas.

Claude Code

• Utiliza la herramienta Skill para invocar skills.
• Cuando se invoca una skill, su contenido se carga y se presenta al agente — el agente debe seguirlo directamente.
• El agente no debe usar la herramienta Read para abrir archivos de skills; debe usar la herramienta Skill para ello.

Gemini CLI

• Las skills se activan mediante la herramienta activate_skill.
• Gemini carga los metadatos de las skills al inicio de la sesión y activa el contenido completo bajo demanda.
• Cuando se activa una skill, el agente debe seguir las instrucciones proporcionadas por esa skill.

Otros entornos

Para entornos más allá de Claude Code y Gemini CLI:

• Consulta la documentación de tu plataforma para ver cómo gestiona la activación de skills o los flujos de trabajo basados en herramientas.
• Usa las referencias de este repositorio como guía para mapear los nombres genéricos de herramientas "superpowers" a los equivalentes de tu plataforma.

6. Mapear herramientas a entornos tipo Codex

Si utilizas Codex CLI o un entorno similar, lee:

• references/codex-tools.md

Conceptos clave de esa referencia:

• Las skills usan por defecto nombres de herramientas de Claude Code.
• El archivo proporciona una tabla de mapeo entre las herramientas de superpowers y sus equivalentes en Codex, incluyendo:
  • Task → spawn_agent
  • Múltiples llamadas Task → múltiples llamadas spawn_agent
  • Resultado de una Task → wait
  • Finalización de una Task → close_agent
  • TodoWrite → update_plan
  • Skill → manejo nativo de skills
  • Read / Write / Edit / Bash → herramientas correspondientes de archivos y shell en Codex

También documenta:

• Cómo habilitar soporte multi‑agente en Codex añadiendo a ~/.codex/config.toml:

[features]
multi_agent = true

• Cómo gestionar el lanzamiento de agentes con nombre cuando Codex no dispone de un registro de agentes con nombre, incluyendo leer un archivo de prompt (como agents/code-reviewer.md), rellenar placeholders y lanzar un agente worker con ese prompt.

7. Mapear herramientas a Gemini CLI

Para el uso con Gemini CLI, lee:

• references/gemini-tools.md

Esta referencia explica cómo se mapean las herramientas estándar de superpowers a las herramientas de Gemini CLI, por ejemplo:

• 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

También indica que:

• Gemini CLI no admite subagentes — no existe un equivalente a la herramienta Task.
• Las skills que dependen de subagentes (como subagent-driven-development o dispatching-parallel-agents) pasan a ejecutarse en una única sesión mediante otras skills de planificación (como executing-plans).
• Gemini CLI incluye herramientas adicionales sin equivalente directo en Claude Code, como list_directory, save_memory, ask_user, tracker_create_task y enter_plan_mode / exit_plan_mode.

8. Orden de lectura recomendado

Para sacar el máximo partido de using-superpowers en un nuevo workspace:

1. Empieza por SKILL.md
   • Comprende la prioridad de instrucciones y las reglas de invocación obligatoria de skills.
2. Abre references/codex-tools.md (si usas Codex o un entorno similar)
   • Configura el soporte multi‑agente y los mapeos de herramientas.
3. Abre references/gemini-tools.md (si usas Gemini CLI)
   • Aprende el mapeo de herramientas y la ausencia de soporte para subagentes.

A partir de ahí, puedes adaptar estos patrones a tus propias herramientas y archivos de configuración.

---

Preguntas frecuentes

¿Cómo instalo la skill using-superpowers?

Usa Skills CLI para añadirla desde el repositorio obra/superpowers:

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

Una vez instalada, abre SKILL.md para ver las reglas principales y la carpeta references/ para los mapeos de herramientas específicos de cada plataforma.

¿Cuándo debe ejecutar un agente using-superpowers?

La skill using-superpowers está diseñada para ejecutarse al inicio de una conversación o tarea de tu agente principal. Debe usarse cuando un agente vaya a:

• Empezar a trabajar en un proyecto que tenga skills de superpowers
• Decidir qué skills utilizar para una nueva solicitud
• Operar en un entorno de desarrollo con múltiples herramientas y múltiples plataformas

Los subagentes lanzados para tareas estrechas deben omitir esta skill y seguir en su lugar los prompts o instrucciones que se les pasen.

¿using-superpowers sobrescribe las instrucciones del usuario?

No. La skill indica explícitamente que las instrucciones del usuario siempre tienen prioridad. La prioridad de instrucciones es:

1. Instrucciones del usuario (incluyendo CLAUDE.md, GEMINI.md, AGENTS.md y los prompts directos del usuario)
2. Skills de superpowers como using-superpowers
3. Comportamiento por defecto del prompt de sistema

Si hay un conflicto entre una instrucción del usuario y una skill, el agente debe seguir la instrucción del usuario.

¿Qué significa en la práctica “invocación obligatoria de skills”?

La invocación obligatoria de skills significa:

• Si hay cualquier posibilidad realista de que una skill aplique a la tarea actual, el agente debe invocarla.
• El agente no debe responder ni hacer preguntas de aclaración primero cuando pueda existir una skill relevante.

Esto ayuda a garantizar que:

• Las skills de seguridad y de flujo de trabajo se apliquen de forma constante
• Los agentes se apoyen en procedimientos probados en lugar de improvisar

¿Cómo afecta using-superpowers a Claude Code?

En Claude Code:

• Los agentes deben usar la herramienta Skill para cargar y seguir las skills, incluida using-superpowers.
• No deben usar la herramienta Read para abrir directamente archivos de skills.
• Una vez que using-superpowers está activa, el agente sigue sus directrices de prioridad de instrucciones e invocación de skills.

Puedes combinar esto con otras skills del mismo repositorio para crear un flujo de trabajo de desarrollo robusto y basado en skills.

¿Cómo funciona using-superpowers con Gemini CLI?

Con Gemini CLI:

• Las skills se activan mediante la herramienta activate_skill.
• using-superpowers explica que Gemini carga los metadatos de las skills al inicio de la sesión y que el contenido completo se activa cuando se solicita.
• Los nombres de herramientas mencionados en las skills de superpowers se mapean a herramientas de Gemini CLI en references/gemini-tools.md.

Ten en cuenta que Gemini CLI no admite subagentes; las skills que dependen del lanzamiento de subagentes pasan automáticamente a patrones de ejecución de sesión única.

¿Puedo usar using-superpowers en otras plataformas de agentes?

Sí, siempre que tu plataforma admita el concepto de skills o tools:

• Utiliza SKILL.md como referencia principal para el comportamiento y la prioridad de instrucciones.
• Revisa references/codex-tools.md y references/gemini-tools.md como ejemplos de cómo mapear los nombres de herramientas de superpowers a tu plataforma.
• Implementa una capa de mapeo similar para alinear las herramientas de tu plataforma con las expectativas de la skill.

Es posible que tengas que adaptar o ampliar los mapeos según las capacidades de tu plataforma.

¿Qué archivos debo leer primero tras instalar la skill?

Para una puesta en marcha rápida y práctica:

1. SKILL.md — comportamiento principal, prioridad de instrucciones y regla de invocación obligatoria de skills.
2. references/codex-tools.md — si utilizas Codex o un entorno similar a Codex.
3. references/gemini-tools.md — si utilizas Gemini CLI.

A partir de ahí, puedes explorar otras skills del repositorio obra/superpowers para construir un flujo de trabajo más completo.

¿Es suficiente using-superpowers por sí sola?

using-superpowers proporciona la base de cómo deben descubrirse y aplicarse las skills, pero es mucho más potente cuando se combina con otras skills del mismo ecosistema (para planificación, revisión de código, pruebas, etc.).

Úsala como la primera capa de la configuración de tus agentes y añade encima skills específicas de dominio según las necesidades de tu proyecto.