---
name: project-addons
description: >-
  Instalar y configurar complementos (add-ons) en el repo del usuario según
  references/<addon>-<tecnologia>.md junto a este SKILL. Usar al pedir addon,
  integración (p. ej. MSAL en Angular), /project-addons o instalar complemento
  en una app.
license: MIT
allowed-tools: Bash
---

# Addons de proyecto (instalar y configurar)

## Purpose

Un **addon** es una **receta versionada** que añade una integración concreta al código del usuario: dependencias, archivos y configuración **sin** improvisar. El detalle ejecutable vive **solo** en `references/<addon>-<tecnologia>.md` **en la carpeta de este skill** (no en el repo de la app).

**Disparadores (cualquiera):** el usuario pide instalar/configurar un addon, invoca `/project-addons`, o dice “addon”, “complemento”, “MSAL”, u otra fila del [Catálogo](#catálogo-de-addons-tabla-canónica).

## Contrato para el agente (obligatorio)

Leer esta sección **antes** de bash o ediciones.

| Regla | Texto |
| ----- | ----- |
| R1 | Resolver el archivo de referencia **solo** como: `<directorio_de_este_SKILL.md>/references/<addon>-<tecnologia>.md>`. **Nunca** buscar `references/` en la raíz del workspace de la app como sustituto. |
| R2 | **No** ejecutar pasos del addon hasta haber **leído por completo** el `.md` de referencia resuelto en R1. Si el archivo no existe: **parar** y decir que falta la referencia en el skill (o copia incompleta del skill). |
| R3 | Comandos de paquetes: **solo** `npm install …` en el directorio del `package.json` que indique la referencia, salvo excepción **explícita** escrita en esa referencia. |
| R4 | Rutas, nombres de archivo y snippets: **solo** los que aparezcan en la referencia; el skill genérico **no** define paths de MSAL, `environment`, etc. |
| R5 | Si el catálogo tiene más de una tecnología para un producto y el usuario no dio stack: **preguntar** y **parar** hasta respuesta. |
| R6 | Si el proyecto no coincide con la **Tecnología** declarada al inicio de la referencia: **avisar**, **no** aplicar pasos “a ciegas”. |

## Árbol de decisión (orden fijo)

1. **Entrada:** extraer `addon` (producto) y `tecnologia` (stack) del mensaje del usuario.
2. **Si falta `tecnologia`** y el catálogo tiene varias tecnologías para ese addon → listar filas aplicables y **preguntar** → **fin de turno** hasta respuesta.
3. **Normalizar** nombres de archivo: minúsculas, sin espacios; archivo = `<addon>-<tecnologia>.md` (ej. addon msal + Angular → `msal-angular.md`).
4. **Si** `references/<addon>-<tecnologia>.md` no existe junto a este `SKILL.md` → mensaje de error según R2 → **fin**.
5. **Leer** el archivo completo (una sola pasada antes de ejecutar).
6. **Ejecutar** secciones en el **orden** en que la referencia los numere o titule (no reordenar).
7. **Verificar** si el entorno lo permite: build o lint mínimo en archivos tocados.
8. **Salida:** resumen de cambios + checklist de pendientes que la referencia exija (secretos, URIs, etc.).

## Scope

**Incluye:** identificar catálogo o archivo de referencia; leer referencia al completo; `npm install` cuando toque; ediciones según referencia; pendientes explícitos.

**No incluye:** publicar paquetes; mantener plantillas ajenas; documentación US/TK salvo petición aparte; añadir addon nuevo sin crear `references/<addon>-<tecnologia>.md` **y** fila en el catálogo.

## Inputs

- Repositorio de aplicación (raíz con `package.json` o paquete de monorepo indicado).
- Par **addon + tecnología** alineado al catálogo. Si el usuario solo dice el producto y hay ambigüedad → preguntar (R5).

## Outputs

- Cambios que la referencia ordene.
- Resumen + checklist de valores humanos/CI según la referencia.

## Steps (resumen; el contrato y el árbol mandan)

1. Confirmar addon y stack (catálogo); si falta stack y hay ambigüedad, preguntar.
2. Cargar `<skillDir>/references/<addon>-<tecnologia>.md`; leer entero.
3. Ejecutar en el repo de la app en el orden de la referencia.
4. Verificar compilación/lint si es posible.
5. Cerrar con resumen y pendientes.

## Examples

**Entrada:** «Instala MSAL en este proyecto Angular.»

**Proceso:** Resolver `references/msal-angular.md` junto a este skill → leer → ejecutar en el repo de la app.

**Salida:** Cambios aplicados + recordatorio de credenciales si la referencia lo marca.

## Anti-patterns

- Ejecutar sin leer la referencia en la carpeta del skill.
- Exigir `references/` dentro del repo de la aplicación.
- Asumir rutas desde este SKILL en lugar de desde la referencia.
- Añadir fila al catálogo sin el archivo de referencia.

## Notes

### Ubicación de las referencias

- `references/` es **siempre** relativo al directorio que contiene este `SKILL.md`.
- Ejemplos de `skillDir`: `…/.cursor/skills/project-addons/` o `…/factor-ai-tools/src/lib/skills/project-addons/`.

### Convención de nombres de referencia

- Patrón: `references/<addon>-<tecnologia>.md` (minúsculas, guiones).
- Cada archivo debe declarar **Tecnología** al inicio (tabla o sección) para validar alineación con el proyecto.

### Catálogo de addons (tabla canónica)

| `addon_id` | `tecnologia` | Archivo de referencia (relativo al skill) |
| ---------- | ------------ | ------------------------------------------- |
| `msal`     | `angular`    | `references/msal-angular.md`                |

**Extender el skill:** (1) crear `references/<addon>-<tecnologia>.md` con tecnología explícita, comandos y checklist; (2) añadir fila a la tabla anterior con los mismos nombres de columnas.