Conceptos básicos de las habilidades del agente

.cursor/skills/
├── api-scaffold/
│   └── SKILL.md
├── queue-worker/
│   └── SKILL.md
├── node-upgrade/
│   └── SKILL.md
└── incident-triage/
    └── SKILL.md

## Fijación de pila
- Node.js 24.18.0 (LTS activa)
- TypeScript 5.6+
- Fastify 5 / NestJS 11 / Express 5 (según ADR del servicio)
- npm 10+

# Habilidad de andamiaje de API
 
## Qué hace esta habilidad
Arranca Fastify 5 + TypeScript + pruebas + Dockerfile.
 
## Cuándo invocarla
- Nuevo microservicio en monorepo
- Reemplazo de un stub de Express heredado
 
## Entradas (obligatorias)
- ADR del framework (Fastify vs Nest)
- Nombre del servicio, puerto, ruta de salud
- Si se requiere Postgres/Redis desde el primer día
 
## Salidas
- Lista de verificación del árbol de archivos
- Scripts de package.json que coinciden con CI
- Verificación: npm run typecheck && npm test
 
## Barreras de seguridad
- Nunca confirmar .env con secretos reales
- Valor predeterminado de ESM: "type": "module"
- Ruta de salud antes de las rutas de negocio
 
## Fijación de pila
Node.js 24.18.0 · TypeScript 5.6+ · Fastify 5
 
## Ejemplos de prompts
Ver §10 a continuación.

## Fijación de pila (obligatoria)
- Node.js 24.18.0 - NO ejemplos de Node 18 con `require()`
- "type": "module" - NO patrones de CommonJS `__dirname`
- Fastify 5 `await app.listen()` - NO escucha de callback de Fastify 3

## Política de invocación del equipo
1. Nombra la habilidad en el prompt: "Usar la habilidad de andamiaje de API para billing-api"
2. Adjunta el ADR o service.yaml si existe
3. El agente debe generar comandos de verificación antes de declarar que ha terminado
4. El humano ejecuta npm ci && npm test localmente antes de la fusión
5. Nunca fusionar automáticamente PRs generados por habilidades sin revisión

## Barreras de seguridad
- No hay secretos en los archivos generados; usa marcadores de posición .env.example
- No hay `any` en TypeScript generado sin un TODO explícito
- Los workers no deben compartir el proceso del servidor HTTP
- Manejadores de apagado elegante en API y workers
- npm audit --audit-level=high debe pasar antes de "terminado"

cd services/orders-api
npm ci
npm run typecheck
npm test
npm run build
docker build -t orders-api:local .
curl -sf http://localhost:3000/health

docs/skills/README.md          # índice con disparadores de invocación
.cursor/skills/                # rutas nativas de Cursor
.github/skills/                # opcional: compartido a través de submódulo

# Índice de habilidades de SME de Node
| Habilidad | Disparador | Propietario |
|-----------|------------|-------------|
| api-scaffold | nuevo servicio | equipo de plataforma |
| queue-worker | tarea asíncrona | equipo de plataforma |
| node-upgrade | aumento de LTS | infraestructura |
| incident-triage | API SEV1/2 | de guardia |

Prompt: "Usar la habilidad de andamiaje de API para notifications-api, luego la habilidad de worker de cola para la cola de correo electrónico"
 
Orden:
1. Andamiaje HTTP + salud + logger
2. Agregar URL de Redis a .env.example
3. Agregar entrada de worker en package.json "worker:email"
4. Verificar API y worker por separado

Usar la habilidad de andamiaje de API:
- Servicio: inventory-api
- Framework: Fastify 5 según ADR-012
- Necesidades: Postgres, no Redis el primer día
- Salida: árbol completo + Dockerfile + stub de trabajo de GitHub Actions

Usar la habilidad de actualización de Node:
- Actual: Node 20.18.0 en Docker y .nvmrc
- Objetivo: Node 24.18.0 LTS activa
- Monorepo: 6 servicios, npm workspaces
- Salida: matriz de cambios importantes + PRs de migración ordenados

Usar la habilidad de triaje de incidentes:
- Síntoma: 502 de ingreso, latencia p95 12s, conexiones de Postgres al máximo
- Servicio: orders-api v2.4.1 desplegado hace 40m
- Salida: lista de verificación T+0 a T+60 con decisión de reversión