Workflow Multi-Repo¶

Guía para desarrolladores que trabajan con múltiples repositorios y quieren evitar copias redundantes de skills en cada uno.

El problema¶

Por default, rai init copia las skills de RaiSE dentro de cada proyecto (.claude/skills/). Esto funciona bien con 1-2 repos, pero si manejas 10+, terminas con:

Copias idénticas de 48+ skills en cada repo
Updates manuales repo por repo cuando RaiSE se actualiza
Confusión sobre cuál versión de las skills es la "buena"

La solución: CLI global + skills en user space¶

La idea es simple:

Un solo rai instalado globalmente (disponible en cualquier directorio)
Una sola copia de skills en tu espacio de usuario (~/.claude/skills/)
rai init --no-skills en cada repo (no copia skills localmente)

Claude Code busca skills en ~/.claude/skills/ automáticamente — no necesitas configuración extra.

Paso 1: Instalar raise-cli global¶

Si ya seguiste la guía de setup, ya tienes esto. Si no:

uv tool install raise-cli

Verifica:

rai --version        # → raise-cli version X.Y.Z
which rai            # → ~/.local/bin/rai

Alternativa: pipx¶

pipx install raise-cli

Ambos métodos crean un entorno aislado y ponen rai en tu PATH. uv tool es más rápido y es el método recomendado.

Paso 2: Skills en user space¶

Ejecuta rai init una vez en cualquier directorio para poblar las skills en ~/.claude/skills/:

mkdir -p ~/raise-setup && cd ~/raise-setup
rai init

Esto copia las skills a .claude/skills/ dentro de ese directorio. Muévelas a tu espacio de usuario:

cp -r .claude/skills/* ~/.claude/skills/

O, si ya tienes un proyecto donde ejecutaste rai init, copia desde ahí:

cp -r ~/projects/mi-proyecto/.claude/skills/* ~/.claude/skills/

Verifica:

ls ~/.claude/skills/ | head -10
# Deberías ver: rai-session-start, rai-story-start, rai-debug, etc.

Paso 3: Inicializar repos sin copiar skills¶

En cada nuevo repo, usa --no-skills:

cd ~/projects/hotel-booking
rai init --no-skills

Esto inicializa la configuración de RaiSE (.raise/, CLAUDE.md, etc.) pero no copia skills al proyecto. Si ya tienes skills en ~/.claude/skills/, rai init detecta esto automáticamente y te pregunta:

Found 48/48 RaiSE skills in /home/tu-usuario/.claude/skills/ (user space).
Skip local copy? [Y/n]:

El default es Y (skip) — presiona Enter para usar las skills del user space.

Árbol de decisión¶

¿Cuántos repos manejas?
│
├─ 1-2 repos
│   └─ rai init (default)
│      Skills se copian al proyecto — simple, sin overhead
│
├─ 3+ repos (mismo desarrollador)
│   └─ rai init --no-skills
│      Skills en ~/.claude/skills/ — una sola copia
│
└─ Equipo (múltiples devs en un repo)
    └─ rai init (default)
       Skills en el repo — versionadas con el código, todos usan las mismas

Regla general: si eres el único dev y tienes muchos repos, usa user space. Si trabajas en equipo en un repo compartido, usa skills per-repo.

Actualizar skills¶

User space (multi-repo)¶

Cuando RaiSE se actualiza, las skills nuevas se incluyen en el paquete. Para actualizar:

# Actualizar el CLI
uv tool upgrade raise-cli

# Re-copiar skills actualizadas
cd /tmp && mkdir raise-update && cd raise-update
rai init
cp -r .claude/skills/* ~/.claude/skills/
cd .. && rm -rf raise-update

Per-repo (default)¶

cd ~/projects/mi-proyecto
rai init --force

Troubleshooting¶

Problema	Causa	Solución
Skills no aparecen en Claude Code	`~/.claude/skills/` no existe o está vacío	Ejecuta el Paso 2
`rai init` sigue copiando skills	No usaste `--no-skills`	Usa `rai init --no-skills` o responde "N" cuando pregunte
Skills desactualizadas	Actualizaste el CLI pero no las skills	Re-copia skills (ver sección Actualizar)
`rai: command not found`	CLI no instalado globalmente	`uv tool install raise-cli`
`~/.local/bin` no está en PATH	Terminal no reconoce `rai`	Agrega `export PATH="$HOME/.local/bin:$PATH"` a tu `~/.bashrc`

Referencia rápida¶

# Setup inicial (una vez)
uv tool install raise-cli           # CLI global
rai init                             # en cualquier dir, genera skills
cp -r .claude/skills/* ~/.claude/skills/  # mover a user space

# Por cada repo nuevo
cd ~/projects/nuevo-repo
rai init --no-skills                 # config sin skills locales

# Actualizar
uv tool upgrade raise-cli            # CLI
# + re-copiar skills (ver sección Actualizar)