---
name: instalar-sistema
description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
user-invocable: false
version: "1.0.1"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
  - "No cargar para actualizar un skill o agente individual; editar el SKILL.md o agente directamente en `habilidades/` o `agentes/`."
  - "No cargar para diagnosticar integridad del sistema instalado; usar `/swl:status salud`."
  - "No cargar para añadir skills de `_userland/` al core; usar `/swl:contribuir`."
evolvable: true  # default para skill estandar
---
# Skill: instalar-sistema

Gestiona la instalación, actualización y verificación del sistema SWL (swl-ses) dentro de un proyecto mediante Claude Code.

## Cuándo se activa

Este skill se activa proactivamente cuando:

- El usuario dice "instala SWL", "quiero usar el sistema SWL", "configura SWL en este proyecto"
- El usuario menciona perfiles: "necesito el perfil backend-python", "instala perfil completo"
- Se detecta que el proyecto no tiene componentes SWL instalados (no hay `.claude/.swl-install-state.json`)
- El usuario pide actualizar SWL: "actualiza SWL", "quiero la última versión"

NO se activa cuando:
- SWL ya está instalado y el usuario no pidió cambios
- El usuario está trabajando normalmente con los agentes/skills ya instalados

## Cuándo NO cargar

- SWL está instalado y `npx swl-ses doctor` pasa sin errores; reinstalar no resuelve problemas de uso.
- El usuario quiere modificar un skill o agente específico; editar los archivos en `habilidades/` o `agentes/` directamente.
- Se quiere diagnosticar por qué algo del sistema no funciona; usar `/swl:status salud` que ejecuta validaciones sin reinstalar.
- Se quiere incorporar skills de `_userland/` al core del sistema; ese flujo es `/swl:contribuir`, no una reinstalación.

## Paquete npm

```
@saulwade/swl-ses          (canónico, npmjs.org — recomendado)
@saul-wade/swl-ses         (mirror, GitHub Packages — requiere token)
```

Registry canónico: `https://registry.npmjs.org/` (sin auth para instalar)
Mirror: `https://npm.pkg.github.com` (auth con token de GitHub en `~/.npmrc`)
Requiere: Node.js >= 22

## Comandos CLI disponibles

| Comando | Función |
|---------|---------|
| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` y `_userland/` |
| `npx @saulwade/swl-ses@latest install --target claude --profile <perfil>` | Instala componentes |
| `npx @saulwade/swl-ses@latest doctor` | Verifica instalación |
| `npx @saulwade/swl-ses@latest update` | Actualiza componentes |
| `npx @saulwade/swl-ses@latest uninstall --target claude` | Desinstala componentes |

## Perfiles

| Perfil | Descripción | Componentes |
|--------|-------------|-------------|
| `core` | Mínimo viable | 13 agentes, 20 skills, 9 comandos, 5 reglas, 3 hooks |
| `backend-python` | Python fullstack | Core + 7 skills Python + 3 skills API + 3 skills datos |
| `backend-node` | Node.js fullstack | Core + 2 skills Node + 3 skills API |
| `frontend-react` | React frontend | Core + 2 skills React + 5 skills estilos + 3 skills UX |
| `frontend-angular` | Angular frontend | Core + 2 skills Angular + 5 skills estilos + 3 skills UX |
| `fullstack-python-angular` | Python + Angular | Backend Python + Frontend Angular |
| `fullstack-node-react` | Node + React | Backend Node + Frontend React |
| `mobile` | Mobile dev | Core + 2 skills mobile + frontend agentes |
| `devops` | Infraestructura | Core + 6 skills infra + 3 skills seguridad |
| `completo` | Todo SWL | 37 agentes, 60 skills, 14 comandos, 11 reglas, 6 hooks |

## Flujo de instalación

### Instalación nueva (proyecto sin SWL)

```bash
# 1. Inicializar estructura
npx @saulwade/swl-ses@latest init

# 2. Instalar componentes (elegir perfil según necesidad)
npx @saulwade/swl-ses@latest install --target claude --profile <perfil>

# 3. Verificar
npx @saulwade/swl-ses@latest doctor
```

### Actualización (SWL ya instalado)

```bash
# Re-instala con el mismo perfil, sobrescribiendo archivos
npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --force
```

### Cambio de perfil

```bash
# Instalar con nuevo perfil (sobrescribe)
npx @saulwade/swl-ses@latest install --target claude --profile <nuevo-perfil> --force
```

### Instalación global (todos los proyectos)

```bash
npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --global
```

## Detección automática de stack tecnológico

El instalador detecta automáticamente los lenguajes presentes en el proyecto y filtra las reglas de lenguaje irrelevantes **antes** de copiarlas a `.claude/rules/`. Esto es crítico porque Claude Code auto-carga todos los `.md` de `.claude/rules/` en cada conversación.

**Lenguajes detectados automáticamente:**

| Lenguaje | Indicadores |
|----------|-------------|
| `java` | `pom.xml`, `build.gradle`, `build.gradle.kts`, archivos `.java` |
| `go` | `go.mod`, archivos `.go` |
| `rust` | `Cargo.toml`, archivos `.rs` |
| `csharp` | Archivos `.csproj`, `.sln`, `.cs` |
| `kotlin` | Archivos `.kt`, `.kts` |
| `swift` | `Package.swift`, directorio `Sources/`, archivos `.swift` |
| `php` | `composer.json`, `artisan`, archivos `.php` |
| `nextjs` | `next.config.js/ts/mjs/cjs` |

**Comportamiento:**
- En un proyecto Python/Angular/TypeScript: **0 reglas de lenguaje instaladas** (Python/TS/Angular no tienen `reglas/lenguajes/` propias)
- En un proyecto Java: solo las 5 reglas de `reglas/lenguajes/java/` se instalan
- Perfil `completo` en proyecto Python: instala `reglas-core` + `reglas-calidad` únicamente (ahorra ~700 líneas de contexto)

**Omitir la detección (instalar todos los lenguajes):**
```bash
npx swl-ses install --target claude --profile completo --all-langs
```

## Qué instala y dónde

| Componente | Destino | Claude Code lo descubre |
|------------|---------|------------------------|
| Agentes (.md) | `.claude/agents/` | Si — disponibles como `subagent_type` |
| Skills (dirs con SKILL.md) | `.claude/skills/` | Si — aparecen en system reminders, auto-activación |
| Comandos (.md) | `.claude/commands/swl/` | Si — disponibles como `/swl:*` slash commands |
| Reglas generales (.md) | `.claude/rules/` | Si — cargadas automáticamente en cada conversación |
| Reglas de lenguaje (.md) | `.claude/rules/LANG/` | Si — solo para lenguajes detectados en el proyecto |
| Hooks (.js) | `./hooks/` | Si — registrados automáticamente en `.claude/settings.json` |
| Plantillas | `.planning/` | N/A — templates para planeación |

## Prerrequisitos para instalación remota

Si el usuario no tiene el registry configurado:

```bash
# Configurar registry de GitHub Packages (una vez por máquina)
npm config set @saul-wade:registry https://npm.pkg.github.com

# Configurar token en ~/.npmrc (una vez por máquina)
# Agregar línea: //npm.pkg.github.com/:_authToken=<GITHUB_CLASSIC_PAT>
```

El token debe ser un **GitHub Classic PAT** con scopes `read:packages`.

## Detección de instalación existente

Para verificar si SWL está instalado:

```bash
# Verificar archivo de estado
cat .claude/.swl-install-state.json 2>/dev/null

# Verificar agentes SWL
ls .claude/agents/*-swl.md 2>/dev/null | head -5

# Verificar hooks registrados
cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
```

## Gotchas / Errores comunes no obvios

- **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.
- **`~/.npmrc` sin el token configurado bloquea la instalación silenciosamente**: `npx @saulwade/swl-ses@latest init` falla con `401 Unauthorized` desde GitHub Packages. Causa: el token de GitHub Packages no está en `~/.npmrc`. Solución: configurar el `_authToken` en `~/.npmrc` y verificar con `npm whoami --registry https://npm.pkg.github.com` antes de la primera instalación.
- **Cambio de perfil sin `--force` no actualiza componentes existentes**: el usuario cambia de `backend-python` a `fullstack-python-angular` pero los nuevos skills de Angular no se instalan porque los archivos ya existen. Causa: el instalador no sobreescribe por defecto. Solución: usar `--force` explícitamente en cambios de perfil: `install --target claude --profile <nuevo-perfil> --force`.
- **markitdown no instalado detectado tardíamente**: el agente intenta convertir un `.docx` en sesión y falla porque `markitdown` no está disponible, interrumpiendo el flujo de trabajo. Causa: el prerequisito de Python se documenta en el skill pero no se verifica automáticamente durante la instalación. Solución: ejecutar `markitdown --version` como parte del checklist post-instalación; si no está disponible, instalarlo antes de iniciar trabajo con documentos Office.
- **Scripts o hooks que leen `swl-install-state.json` solo en el proyecto actual fallan silenciosamente en instalaciones globales**: un hook intenta detectar la versión instalada leyendo `.claude/.swl-install-state.json` relativo al cwd o relativo al directorio del hook; en instalaciones SWL **solo globales** (la mayoría), ese archivo solo existe en `~/.claude/.swl-install-state.json` y el check sale sin resultado — ninguna alerta, ninguna detección, falla invisible. Causa: el instalador crea el state file en la ubicación del target (`~/.claude/` para `--global`, `./.claude/` para `--local`), pero los consumidores suelen buscar en una sola de esas ubicaciones. Solución: cualquier script/hook que dependa del state del instalador debe buscar en **7 ubicaciones** y tomar la del `mtime` más reciente cuando haya varias:
  ```
  ~/.claude/.swl-install-state.json          (global Claude, mayoría de usuarios)
  ./.claude/.swl-install-state.json          (local al proyecto)
  ./.github/.swl-install-state.json          (Copilot)
  ./.codex/.swl-install-state.json           (Codex CLI)
  ./.gemini/.swl-install-state.json          (Gemini CLI)
  ./.opencode/.swl-install-state.json        (OpenCode)
  <dirname-del-script>/../../.claude/.swl-install-state.json   (hook instalado en .claude/hooks/)
  ```
  Ejemplo canónico: `hooks/check-update.js` versión 5.10.3+ implementa esta búsqueda con prioridad por `mtime` y fallback a `package.json` del repo madre. Nunca asumir una sola ubicación de state — el CLI puede instalarse en combinaciones arbitrarias.

## Después de instalar

### Prerequisito Python: markitdown

SWL instala la regla `markitdown.md` en `.claude/rules/` para que los agentes
sepan convertir archivos `.docx`, `.xlsx`, `.pptx` e `.ipynb` a Markdown.
La herramienta en sí requiere instalación manual una vez por máquina:

```bash
pip install markitdown[pdf,docx,pptx,xlsx]
```

Verificar que quedó correctamente instalada:
```bash
markitdown --version
```

> Sin este prerequisito los agentes pueden pedir al usuario el contenido en texto plano,
> pero no podrán convertir archivos Office ni Jupyter automáticamente.

### Comandos disponibles tras la instalación

- `/swl:nuevo-proyecto` — iniciar proyecto desde cero
- `/swl:mapear-codebase` — analizar código existente
- `/swl:planear-fase` — planificar una fase de trabajo
- `/swl:ejecutar-fase` — ejecutar plan con commits atómicos
- `/swl:status salud` — diagnóstico profundo del sistema
