Worktree Manager Skill | Agent Skills

Worktree Manager

Skill para gestionar git worktrees siguiendo la estrategia de carpeta .worktrees/ dentro del repositorio.

Estructura de Worktrees

~/Projects/<github|gitlab>/<project>/
├── .worktrees/                     # ignorado por .gitignore
│   ├── feature-x/                  # worktree para branch feature-x
│   └── bugfix-123/                 # worktree para branch bugfix-123
├── src/                            # archivos del repo (master/main)
└── .gitignore                      # debe incluir .worktrees/

Proceso

Paso 0: Verificar contexto

git rev-parse --is-inside-work-tree
git branch --show-current

Comandos Disponibles

1. Setup Inicial

Ejecutar una vez por proyecto para habilitar worktrees:

grep -q "^\.worktrees/$" .gitignore 2>/dev/null || echo ".worktrees/" >> .gitignore
mkdir -p .worktrees

Si .worktrees/ no estaba en .gitignore, hacer commit:

git add .gitignore
git commit -m "chore: ignore worktrees folder"

2. Crear Worktree (branch nuevo)

# Sintaxis: git worktree add .worktrees/<nombre-branch> -b <nombre-branch>
git worktree add .worktrees/feature-nueva-funcionalidad -b feature-nueva-funcionalidad

El branch debe seguir convenciones:

feature/<descripcion> o feature-<descripcion> para nuevas features
bugfix/<descripcion> o bugfix-<descripcion> para correcciones
hotfix/<descripcion> para arreglos urgentes
chore/<descripcion> para tareas de mantenimiento

3. Crear Worktree desde branch existente

Para revisar un PR o trabajar en un branch remoto existente:

git fetch origin
git worktree add .worktrees/<nombre-branch> origin/<nombre-branch>

4. Listar Worktrees

git worktree list

5. Trabajar en Worktree

IMPORTANTE: cd no persiste entre Bash tool calls en Claude Code. Usar paths absolutos o encadenar con &&:

# Encadenar con && para que cd persista
cd .worktrees/<nombre-branch> && git status

# O usar paths absolutos
git -C .worktrees/<nombre-branch> status

IMPORTANTE: No usar git add . — siempre agregar archivos especificos:

cd .worktrees/<nombre-branch> && git add src/feature.ts src/feature.test.ts
git commit -m "feat: descripcion del cambio"
git push -u origin <nombre-branch>

6. Cleanup despues de Merge

Una vez que el PR fue mergeado, limpiar desde el directorio raiz:

git worktree remove .worktrees/<nombre-branch>
git push origin --delete <nombre-branch>
git branch -d <nombre-branch>

7. Podar Referencias Huerfanas

git worktree prune

Principios Clave

| Principio | Descripcion | |-----------|-------------| | Worktrees son temporales | No son casas permanentes, se eliminan despues del merge | | Main siempre limpio | El repo principal siempre esta en main/master | | Nombres descriptivos | Carpeta del worktree = nombre del branch | | Cleanup obligatorio | Siempre limpiar despues del merge del PR |

Preguntas al Usuario

Antes de crear un worktree, preguntar:

Nombre del branch: "Como quieres llamar al branch?" (sugerir formato feature-* o bugfix-*)
Confirmar estructura: Si es primera vez, confirmar que se agregara .worktrees/ a .gitignore

Antes de cleanup, confirmar:

PR mergeado?: "El PR ya fue mergeado? Confirmar antes de eliminar el worktree."
Branch remoto: "Eliminar tambien el branch remoto?"

Para ejemplos completos de flujo de trabajo, leer references/workflow-examples.md. Para resolver errores comunes, leer references/troubleshooting.md.

Agent Skills: Worktree Manager

Install this agent skill to your local

Skill Files