repo_Claude/.claude/skills/init-jupyter/SKILL.md

---
name: init-jupyter
description: Inicializa entorno Jupyter para exploración de datos con MCP compartido. Autodetecta puerto y configura repo.
argument-hint: [ruta-proyecto]
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob
---

# Inicializar Entorno Jupyter para Data Science

Skill para preparar cualquier repo para exploración de datos con Jupyter + Claude colaborando en kernel compartido.

## PASO 0: Verificar estado actual del repo

**Ejecutar estas comprobaciones primero:**

```bash
# 1. ¿MCP instalado globalmente?
which jupyter-mcp-server && echo "MCP_OK" || echo "MCP_NO"

# 2. ¿Repo ya configurado para Jupyter?
[ -f .claude/settings.local.json ] && grep -q "jupyter" .claude/settings.local.json && echo "REPO_CONFIG_OK" || echo "REPO_NO_CONFIG"

# 3. ¿Jupyter corriendo en este repo?
pgrep -af "jupyter" | grep "$(pwd)" && echo "JUPYTER_RUNNING" || echo "JUPYTER_STOPPED"

# 4. ¿CLAUDE.md tiene reglas Jupyter?
[ -f .claude/CLAUDE.md ] && grep -q "JUPYTER HABILITADO" .claude/CLAUDE.md && echo "RULES_OK" || echo "RULES_NO"
```

### Resultado: MCP NO instalado

```bash
uv tool install jupyter-mcp-server
```

Informar:
```
MCP jupyter-mcp-server instalado.
Ejecuta /exit y vuelve a entrar para recargar.
Después ejecuta /init-jupyter de nuevo.
```
**DETENER AQUÍ**

### Resultado: Repo YA configurado + Jupyter corriendo

Informar:
```
Este repo ya tiene Jupyter configurado y está corriendo.
Puedes empezar a trabajar directamente con notebooks via MCP.
```
**DETENER AQUÍ** (no hace falta reconfigurar)

### Resultado: Repo YA configurado + Jupyter NO corriendo

Informar:
```
Este repo tiene Jupyter configurado pero no está corriendo.
Ejecuta ./run-jupyter-lab.sh en otra terminal para iniciarlo.
```
**DETENER AQUÍ**

### Resultado: Repo NO configurado → Continuar con PASO 1

---

## PASO 1: Detectar ruta de trabajo

```bash
RUTA="${1:-.}"
cd "$RUTA"
pwd
```

---

## PASO 2: Verificar si Jupyter ya corre en ESTE repo

```bash
# Buscar proceso jupyter con el directorio actual
REPO_PATH=$(pwd)
pgrep -af "jupyter" | grep -E "(lab|notebook)" | grep "$REPO_PATH" || echo "NO_JUPYTER"
```

- Si encuentra proceso → Informar "Jupyter ya está corriendo en este repo" y saltar a Paso 6
- Si NO encuentra → Continuar

---

## PASO 3: Detectar puerto libre (autodetección)

```bash
# Encontrar primer puerto libre entre 8888-8899
for port in 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899; do
  if ! lsof -i:$port >/dev/null 2>&1; then
    echo $port
    break
  fi
done
```

Guardar el puerto detectado para usarlo en los siguientes pasos.

---

## PASO 4: Crear/Actualizar archivos del proyecto

### 4a. Crear estructura si no existe

```bash
mkdir -p .claude notebooks
```

### 4b. Crear `run-jupyter-lab.sh` con puerto autodetectado

Crear el archivo con el PUERTO detectado en Paso 3:

```bash
cat > run-jupyter-lab.sh << 'SCRIPT'
#!/bin/bash
# Jupyter Lab para colaboración Claude + Usuario
# Generado por /init-jupyter

# Autodetectar puerto libre
find_free_port() {
    for port in 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899; do
        if ! lsof -i:$port >/dev/null 2>&1; then
            echo $port
            return
        fi
    done
    echo 8888
}

PORT=${1:-$(find_free_port)}

# Guardar puerto para que Claude lo lea
echo $PORT > .jupyter-port

# Activar entorno si existe
source .venv/bin/activate 2>/dev/null || true

echo "══════════════════════════════════════════════════════"
echo "  Jupyter Lab iniciando en puerto $PORT"
echo "══════════════════════════════════════════════════════"
echo ""
echo "  Abre: http://localhost:$PORT"
echo ""
echo "  Claude se conectará al kernel cuando abras un notebook"
echo "  Usa Ctrl+C para detener"
echo ""
echo "══════════════════════════════════════════════════════"

jupyter lab \
    --port=$PORT \
    --no-browser \
    --NotebookApp.token='' \
    --NotebookApp.password='' \
    --NotebookApp.disable_check_xsrf=True \
    --ServerApp.allow_origin='*' \
    --ServerApp.root_dir="$(pwd)"
SCRIPT
chmod +x run-jupyter-lab.sh
```

### 4c. Crear/Actualizar `.claude/settings.local.json`

Usar el PUERTO detectado:

```bash
cat > .claude/settings.local.json << EOF
{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": [
        "--jupyter-url", "http://localhost:PUERTO",
        "--start-new-runtime", "false"
      ]
    }
  }
}
EOF
```

(Reemplazar PUERTO por el valor real detectado)

### 4d. Añadir/Actualizar instrucciones en `.claude/CLAUDE.md`

**IMPORTANTE**: Las reglas de Jupyter deben ir AL PRINCIPIO del archivo para que nuevas conversaciones las vean inmediatamente.

**Lógica de inserción:**

1. Verificar si existe `.claude/CLAUDE.md`
2. Si existe:
   - Leer contenido actual
   - Si NO contiene "JUPYTER HABILITADO" → prepend (añadir al principio)
   - Si YA contiene → no modificar
3. Si no existe → crearlo con las reglas

**Contenido a insertar AL PRINCIPIO:**

```markdown
# JUPYTER HABILITADO EN ESTE REPO

Este repositorio está configurado para exploración de datos con Jupyter + Claude.

## Estado del entorno
- **Lanzador**: `./run-jupyter-lab.sh`
- **Puerto config**: ver `.jupyter-port` o `.claude/settings.local.json`
- **MCP**: jupyter-mcp-server configurado

## Reglas OBLIGATORIAS para Claude

### 1. SIEMPRE usar MCP jupyter para ejecutar código Python
- Las ejecuciones se ven en tiempo real en Jupyter Lab del usuario
- Compartimos variables y estado del kernel
- **NUNCA usar bash para ejecutar Python en este repo**

### 2. Verificar Jupyter activo ANTES de ejecutar
```bash
pgrep -af "jupyter" | grep "$(pwd)" || cat .jupyter-port 2>/dev/null
```
- Si no está activo → pedir al usuario: "Ejecuta `./run-jupyter-lab.sh` en otra terminal"

### 3. Gestión de notebooks
- Si un notebook tiene >50 celdas → crear uno nuevo
- Nombrar descriptivamente: `01_exploracion.ipynb`, `02_limpieza.ipynb`
- Mantener notebooks enfocados en una tarea

### 4. Antes de código pesado
- Avisar al usuario
- Usar `%%time` o `tqdm` para progreso

---

```

**Comando bash para prepend:**

```bash
# Si CLAUDE.md existe y NO tiene las reglas
if [ -f .claude/CLAUDE.md ]; then
  if ! grep -q "JUPYTER HABILITADO" .claude/CLAUDE.md; then
    # Prepend: crear temp con reglas + contenido original
    cat > .claude/CLAUDE.md.tmp << 'JUPYTER_RULES'
[CONTENIDO DE REGLAS AQUÍ]
JUPYTER_RULES
    cat .claude/CLAUDE.md >> .claude/CLAUDE.md.tmp
    mv .claude/CLAUDE.md.tmp .claude/CLAUDE.md
  fi
else
  # Crear nuevo
  cat > .claude/CLAUDE.md << 'JUPYTER_RULES'
[CONTENIDO DE REGLAS AQUÍ]
JUPYTER_RULES
fi
```

---

## PASO 5: Inicializar entorno Python si no existe

### 5a. Si no existe `pyproject.toml`:

```bash
uv init 2>/dev/null || true
uv venv 2>/dev/null || true
```

### 5b. Instalar dependencias de Jupyter:

```bash
source .venv/bin/activate 2>/dev/null || true
uv add jupyter jupyterlab pandas numpy matplotlib 2>/dev/null || pip install jupyter jupyterlab pandas numpy matplotlib
```

---

## PASO 6: Resumen final al usuario

Mostrar:

```
═══════════════════════════════════════════════════════════════
  Entorno Jupyter configurado en: [RUTA]
═══════════════════════════════════════════════════════════════

  Puerto asignado: [PUERTO]

  Para empezar:
  1. En otra terminal ejecuta: ./run-jupyter-lab.sh
  2. Abre http://localhost:[PUERTO] en tu navegador
  3. Crea o abre un notebook
  4. Yo me conecto automáticamente al kernel compartido

  Archivos creados/actualizados:
  - run-jupyter-lab.sh (lanzador)
  - .claude/settings.local.json (config MCP)
  - .claude/CLAUDE.md (reglas de trabajo)

═══════════════════════════════════════════════════════════════
```

---

## Comandos útiles post-inicialización

```bash
# Ver puerto actual
cat .jupyter-port

# Verificar Jupyter corriendo
pgrep -af jupyter

# Listar kernels activos
curl -s http://localhost:$(cat .jupyter-port)/api/kernels | jq

# Listar notebooks abiertos
curl -s http://localhost:$(cat .jupyter-port)/api/sessions | jq
```

---

## Notas para uso frecuente

- El script `run-jupyter-lab.sh` autodetecta puerto cada vez que se ejecuta
- El archivo `.jupyter-port` siempre tiene el puerto actual
- Si cambias de puerto, actualiza `.claude/settings.local.json` o recarga Claude
- Las reglas en `CLAUDE.md` se mantienen entre sesiones