using-git-worktrees

Visión general de la skill using-git-worktrees

Qué hace la skill using-git-worktrees

La skill using-git-worktrees ayuda a un agente a crear un Git worktree separado para trabajo nuevo en lugar de reutilizar tu checkout actual. Su función real no es solo “ejecutar git worktree add”, sino elegir una ubicación sensata, comprobar que las carpetas locales de worktree estén ignoradas de forma segura y evitar contaminar el espacio de trabajo principal.

Quién debería instalarla

Esta skill encaja especialmente bien para quienes con frecuencia:

• inician trabajo de nuevas funcionalidades sin tocar los cambios actuales
• revisan o implementan varias ramas en paralelo
• quieren flujos de trabajo con IA más seguros y con menos riesgo al cambiar de rama
• necesitan una forma repetible de crear espacios de trabajo aislados entre proyectos

Si a menudo le pides a un asistente “empieza esto en una rama aparte” o “trabaja sin tocar mi árbol actual”, using-git-worktrees es una opción muy adecuada.

La tarea que resuelve

A los usuarios les importa un resultado muy concreto: empezar la implementación en un espacio de trabajo aislado con el menor número posible de errores de preparación. La skill using-git-worktrees resulta útil porque añade un proceso de decisión antes de crear nada:

• prioriza un directorio de worktrees del proyecto si ya existe
• respeta la preferencia documentada del repositorio en CLAUDE.md, si está disponible
• pregunta cuando no hay una opción segura por defecto
• verifica el comportamiento de ignore antes de crear worktrees locales al proyecto

Eso la hace más fiable que un prompt genérico que salta directamente a comandos de shell.

Qué la diferencia de un prompt normal

Un prompt normal puede entender el concepto de Git worktrees, pero aun así pasar por alto detalles de configuración específicos del repositorio. Esta skill da al agente un orden de operaciones definido y comprobaciones de seguridad, especialmente en torno a la ubicación del directorio y el manejo de .gitignore. Esa es la principal diferencia de using-git-worktrees for Git Workflows: menos suposiciones en la preparación, no más teoría sobre Git.

Cuándo esta skill encaja mal

Conviene omitir using-git-worktrees si:

• siempre trabajas en una sola rama y en un solo directorio
• tu entorno no permite directorios de trabajo adicionales
• solo necesitas cambiar rápidamente de rama, no ejecutar en aislamiento
• tu equipo ya tiene un wrapper script fijo que sustituye por completo esta lógica de decisión

En esos casos, un comando de shell simple o el flujo interno de tu equipo puede ser más rápido.

Cómo usar la skill using-git-worktrees

Contexto de instalación de using-git-worktrees

Instálala desde la colección de skills obra/superpowers:

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

Tras instalarla, úsala cuando estés a punto de empezar un trabajo que no debería reutilizar el checkout actual.

Cómo suelen invocar realmente los usuarios la skill

El repositorio deja claro explícitamente que el agente debe anunciar su uso al comienzo. En la práctica, tu petición debería dejar evidente la necesidad de aislamiento, por ejemplo:

• “Usa using-git-worktrees y prepara un workspace aislado para esta funcionalidad.”
• “Antes de implementar, crea un worktree para la rama feature/auth-refresh.”
• “Usa la skill using-git-worktrees para que mis cambios actuales no se toquen.”

Esto aumenta la probabilidad de que el agente siga la skill en lugar de improvisar.

Qué entrada necesita la skill

Para obtener buenos resultados, conviene indicar:

• el nombre de la rama de destino
• si se trata de una rama nueva o de una rama existente
• si prefieres almacenamiento de worktrees local al proyecto o global
• cualquier restricción específica del repositorio, como “debe permanecer bajo la raíz del proyecto”

Entrada mínima útil:

• nombre de la rama o tarea
• permiso para crear un worktree

Entrada mejor:

• nombre de la rama
• política de directorios deseada
• si hay trabajo sin confirmar en el checkout actual
• qué debe ocurrir después de la preparación, por ejemplo “y luego empieza la implementación”

La lógica integrada de selección de directorios

Donde más valor aporta la using-git-worktrees skill es en su flujo de selección de directorios. Sigue esta prioridad:

1. usar .worktrees si ya existe
2. en caso contrario, usar worktrees si existe
3. si no, revisar CLAUDE.md para ver si hay una preferencia documentada
4. si tampoco la hay, pedir al usuario que elija entre:
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

Esto importa porque la dispersión de worktrees se convierte en un problema real de mantenimiento si cada sesión inventa una ubicación distinta.

Comprobaciones de seguridad antes de crear worktrees locales al proyecto

Un detalle clave para adoptar esta skill: si el worktree va a vivir dentro del repositorio, exige verificar antes que el directorio esté ignorado. Eso protege frente a que las carpetas de worktree se rastreen por accidente o ensucien la salida de estado.

Es una ventaja real frente a un uso improvisado. Si tu equipo espera worktrees locales al proyecto, asegúrate de que .worktrees/ o worktrees/ esté ignorado por Git antes de basar el flujo en esta skill.

Patrones de prompt sólidos para usar using-git-worktrees

Prompt débil:

• “Empieza a trabajar en la limpieza de OAuth.”

Prompt más sólido:

• “Usa using-git-worktrees para crear un workspace aislado para la nueva rama feature/oauth-cleanup. Prioriza .worktrees/ si es seguro y está ignorado. Tras la preparación, empieza la implementación sin tocar mi checkout actual.”

Por qué este funciona mejor:

• nombra la skill
• define una rama de destino
• indica la preferencia de directorio
• le dice al agente qué viene después

Flujo recomendado después de la creación

Una secuencia práctica para el using-git-worktrees usage:

1. pedir al agente que use la skill
2. confirmar la ubicación del worktree y el nombre de la rama
3. hacer que el agente traslade el trabajo al nuevo workspace
4. solo entonces empezar ediciones, pruebas o planificación de la implementación

Esta secuencia es especialmente útil cuando tu checkout actual ya tiene cambios sin confirmar.

Archivos que conviene leer primero en el repositorio

Aquí solo hay un archivo fuente realmente relevante: SKILL.md.

Léelo para ver:

• el orden exacto de prioridad de directorios
• el prompt que se espera mostrar al usuario cuando no existe una preferencia
• el requisito de verificación de ignore
• la formulación de activación que indica al agente que anuncie el uso de la skill

Es una skill ligera, así que la cuestión principal al adoptarla es si esa lógica encaja con el flujo Git de tu equipo.

Limitaciones prácticas que conviene conocer antes de depender de ella

La skill es deliberadamente acotada. No parece ofrecer:

• wrapper scripts
• helpers de automatización
• aplicación estricta de nombres de rama
• rutinas de limpieza para worktrees obsoletos
• alternativas específicas por plataforma

Así que using-git-worktrees install te aporta guía de decisión, no un sistema completo de gestión de worktrees. Si necesitas automatización del ciclo de vida, combínala con tus propias herramientas de shell.

Preguntas frecuentes sobre la skill using-git-worktrees

¿using-git-worktrees es buena para principiantes?

Sí, siempre que la persona ya entienda lo básico sobre ramas y quiera un flujo más seguro de “no toques mi workspace actual”. No es un tutorial de Git; es una skill de preparación estructurada. Un principiante total puede seguir necesitando ayuda para entender qué es un worktree y en qué se diferencia de clonar.

¿Qué problema resuelve mejor que los prompts normales?

Los prompts normales suelen saltarse la parte incómoda: dónde debe vivir el worktree y si un directorio local al proyecto está ignorado de forma segura. La using-git-worktrees guide codificada en la skill reduce esos errores de preparación y hace que el comportamiento del agente sea más consistente.

¿Necesito worktrees locales al proyecto para usarla?

No. La skill puede orientar hacia una ubicación global cuando no existe un directorio local y tampoco hay una preferencia documentada en el repositorio. Eso hace que sea útil incluso si no quieres carpetas adicionales dentro del repositorio.

¿Puedo usar using-git-worktrees con ramas existentes?

Sí. El flujo sigue siendo útil al hacer checkout de una rama existente en un workspace separado. El valor principal es el aislamiento, no solo la creación de ramas.

¿Cuándo no debería usar using-git-worktrees?

No la uses cuando:

• solo vas a hacer una edición mínima en tu rama actual
• tu equipo prohíbe ubicaciones de worktree no gestionadas
• ya tienes herramientas internas deterministas que resuelven la ubicación y las reglas de ignore
• tu repositorio tiene restricciones Git poco habituales que la skill no contempla

¿Sustituye esto al conocimiento de Git?

No. La using-git-worktrees skill mejora la disciplina al invocarla y prepararla, pero sigues necesitando criterio básico de Git para nombres de rama, rebase, limpieza y estrategia de merge.

Cómo mejorar la skill using-git-worktrees

Indica con claridad la rama y la intención de directorio

La mejora de calidad más importante es decirle al agente tanto la rama de destino como la política de directorios preferida. Ejemplo:

“Usa using-git-worktrees para la rama fix/cache-invalidation. Si .worktrees/ existe y está ignorado, úsalo; si no, pregunta antes de usar una ubicación global.”

Esto elimina la fuente de ambigüedad más habitual.

Documenta preferencias en CLAUDE.md

Como la skill consulta CLAUDE.md, puedes mejorar los resultados futuros documentando:

• el directorio de worktrees preferido
• si se permiten worktrees locales al proyecto
• convenciones de nombres para ramas o carpetas

Así conviertes aclaraciones repetidas del usuario en una política a nivel de repositorio.

Preconfigura reglas de ignore para directorios locales

Si tu equipo quiere .worktrees/ o worktrees/ dentro del proyecto, añade la regla de ignore por adelantado. Eso hace que la vía de using-git-worktrees for Git Workflows sea más fluida, porque la verificación de seguridad se supera limpiamente en lugar de forzar una discusión en mitad de la tarea.

Vigila los fallos más comunes

Los principales fallos son previsibles:

• el agente crea un worktree en una ubicación no aprobada
• las carpetas locales de worktree no están ignoradas
• el nombre de la rama se infiere mal a partir de una petición de funcionalidad demasiado vaga
• la implementación empieza en el checkout original antes de que el aislamiento se haya completado

La mayoría de estos problemas vienen de prompts incompletos, no de la skill en sí.

Pide confirmación antes de empezar a programar

Un prompt sencillo de mejora:

• “Usa using-git-worktrees y luego informa de la ruta final y la rama antes de hacer cambios.”

Esto detecta errores pronto y resulta especialmente útil en repositorios con varias carpetas anidadas o políticas poco habituales.

Itera después de la primera ejecución

Si la primera salida es aceptable pero no ideal, afina el patrón de trabajo en lugar de reescribirlo todo:

• fija tu ubicación de directorio preferida
• añade una nota en CLAUDE.md
• estandariza el nombrado de ramas en los prompts
• exige explícitamente confirmación antes de editar

Eso hace que el using-git-worktrees usage sea más predecible con el tiempo y reduce la fricción repetida de preparación.