diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..9f80d45 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,62 @@ +# Skills + +Sistema de skills reutilizables para agentes. Las skills son paquetes de instrucciones, scripts y recursos que guian al agente para completar tareas complejas multi-paso. + +## Diferencia entre Tools y Skills + +| | Tools | Skills | +|---|---|---| +| **Nivel** | Funcion atomica | Flujo multi-paso | +| **Invocacion** | Function calling del LLM | El agente busca y carga bajo demanda | +| **Ejemplo** | `ssh_command`, `http_get` | "deploy-service", "log-analyzer" | +| **Ubicacion** | `tools//` | `skills///` | + +## Estructura de una skill + +``` +skills/// +├── SKILL.md ← obligatorio (frontmatter YAML + instrucciones) +├── scripts/ ← opcional, codigo ejecutable +├── references/ ← opcional, docs de referencia +├── templates/ ← opcional, plantillas +└── assets/ ← opcional, archivos estaticos +``` + +## SKILL.md — formato + +```yaml +--- +name: nombre-skill +description: > + Descripcion de que hace y cuando activarse. +--- + +# Instrucciones + +Cuerpo markdown con instrucciones completas (< 500 lineas idealmente). +``` + +## Carga progresiva + +1. **Metadata** (name + description) — siempre en contexto del agente +2. **Instrucciones** (cuerpo SKILL.md) — cuando la skill se activa +3. **Recursos** (scripts/, references/, etc.) — bajo demanda + +## Categorias + +| Categoria | Descripcion | +|-----------|-------------| +| `devops/` | Operaciones, deploy, infraestructura | +| `analysis/` | Analisis de datos, logs, metricas | +| `communication/` | Notificaciones, reportes, mensajeria | +| `coding/` | Desarrollo, code review, refactoring | +| `system/` | Administracion de sistemas, monitoreo | + +## Crear una nueva skill + +1. Crear directorio: `skills///` +2. Crear `SKILL.md` con frontmatter YAML (name + description) y cuerpo markdown +3. Opcionalmente agregar scripts/, references/, templates/, assets/ +4. La skill estara disponible automaticamente para agentes con `skills.enabled: true` + +Ver policy completa en `.claude/policies/create_skill.md` (pendiente). diff --git a/skills/analysis/log-analyzer/SKILL.md b/skills/analysis/log-analyzer/SKILL.md new file mode 100644 index 0000000..4bc15c2 --- /dev/null +++ b/skills/analysis/log-analyzer/SKILL.md @@ -0,0 +1,70 @@ +--- +name: log-analyzer +description: > + Analiza logs de servicios para encontrar errores, patrones y anomalias. + Usa esta skill cuando el usuario pida revisar logs, buscar errores en un + servicio, diagnosticar problemas, o entender que paso en un periodo de tiempo. + Funciona con journalctl, archivos de log, y logs de Docker. +--- + +# Analisis de logs + +## Prerequisitos + +- Tool `ssh_command` habilitada (para logs remotos) +- Acceso al servidor donde estan los logs + +## Flujo + +### 1. Identificar fuente de logs + +Preguntar o inferir del contexto: +- **Servicio**: nombre del servicio o contenedor +- **Periodo**: rango de tiempo a analizar (default: ultima hora) +- **Servidor**: host donde corren los logs +- **Tipo**: systemd (journalctl), archivo (/var/log/...), o Docker + +### 2. Obtener logs + +Segun el tipo de fuente: + +**Systemd (journalctl):** +```bash +ssh_command: "journalctl -u --since '' --no-pager" +``` + +**Archivo de log:** +```bash +ssh_command: "tail -n 500 /var/log//.log" +# o con filtro de tiempo: +ssh_command: "awk '/2024-01-15 14:00/,/2024-01-15 15:00/' /var/log/.log" +``` + +**Docker:** +```bash +ssh_command: "docker logs --since 2>&1 | tail -500" +``` + +### 3. Analisis + +Buscar en los logs: +- **Errores**: lineas con ERROR, FATAL, panic, exception, traceback +- **Warnings**: lineas con WARN, warning +- **Patrones repetitivos**: errores que se repiten (agrupar por tipo) +- **Timestamps**: cuando empezaron los problemas +- **Correlaciones**: errores que ocurren juntos o en secuencia + +### 4. Reporte + +Presentar al usuario: +1. **Resumen**: estado general (saludable / con problemas / critico) +2. **Errores encontrados**: listado agrupado por tipo con conteo +3. **Timeline**: cuando empezaron y si siguen ocurriendo +4. **Causa probable**: si se puede inferir del contexto +5. **Recomendacion**: accion sugerida (restart, fix config, escalar, etc.) + +## Tips + +- Si los logs son muy extensos, obtener primero un conteo de errores y luego los detalles de los mas frecuentes +- Usar `grep -c` para contar antes de traer lineas completas +- Para logs grandes, usar `tail` o rangos de tiempo acotados diff --git a/skills/analysis/log-analyzer/references/.gitkeep b/skills/analysis/log-analyzer/references/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/coding/code-review/SKILL.md b/skills/coding/code-review/SKILL.md new file mode 100644 index 0000000..b67a061 --- /dev/null +++ b/skills/coding/code-review/SKILL.md @@ -0,0 +1,96 @@ +--- +name: code-review +description: > + Revisa codigo fuente buscando bugs, problemas de seguridad, y mejoras. + Usa esta skill cuando el usuario pida revisar un archivo, un diff, o + cambios recientes en un repositorio. Tambien cuando pregunte "que opinas + de este codigo" o "revisa esto". +--- + +# Code review + +## Prerequisitos + +- Tool `ssh_command` o `read_file` para acceder al codigo +- Contexto sobre el lenguaje y framework del proyecto + +## Flujo + +### 1. Obtener el codigo + +Segun el contexto: + +**Archivo especifico:** +```bash +read_file: "" +``` + +**Diff de cambios recientes:** +```bash +ssh_command: "cd && git diff HEAD~1" +# o: +ssh_command: "cd && git diff --staged" +``` + +**PR o branch:** +```bash +ssh_command: "cd && git diff main.." +``` + +### 2. Analisis + +Revisar el codigo buscando: + +**Bugs y errores logicos:** +- Variables no inicializadas o no usadas +- Condiciones de carrera (acceso concurrente sin mutex) +- Nil/null pointer dereferences +- Off-by-one errors +- Resource leaks (archivos, conexiones no cerradas) + +**Seguridad (OWASP top 10):** +- Inyeccion SQL o de comandos +- XSS, CSRF +- Secretos hardcodeados +- Permisos demasiado amplios +- Input no validado + +**Calidad:** +- Funciones demasiado largas (> 50 lineas) +- Duplicacion de codigo +- Nombres poco claros +- Complejidad innecesaria +- Errores silenciados (catch vacio, err ignorado) + +**Estilo y convenciones:** +- Consistencia con el resto del codebase +- Patrones del proyecto (ej: pure core / impure shell en este repo) + +### 3. Reporte + +Formato del review: + +```markdown +## Code Review — + +### Critico +- **[L42]** SQL injection: el parametro `userID` se concatena directamente en la query +- **[L78]** Resource leak: `file` se abre pero nunca se cierra + +### Mejoras sugeridas +- **[L15-20]** Esta logica se repite en handler.go:45 — considerar extraer funcion +- **[L33]** El error de `json.Unmarshal` se ignora silenciosamente + +### Positivo +- Buena separacion de responsabilidades +- Tests cubren los casos principales + +### Resumen +X issues criticos, Y mejoras sugeridas. Prioridad: resolver los criticos antes de merge. +``` + +### 4. Seguimiento + +Si el usuario quiere aplicar las sugerencias: +- Generar los patches concretos para cada issue +- Aplicar cambios uno por uno con confirmacion diff --git a/skills/communication/daily-report/SKILL.md b/skills/communication/daily-report/SKILL.md new file mode 100644 index 0000000..0f94a92 --- /dev/null +++ b/skills/communication/daily-report/SKILL.md @@ -0,0 +1,84 @@ +--- +name: daily-report +description: > + Genera y envia un reporte diario con el estado de servicios, metricas clave + y eventos relevantes. Usa esta skill cuando el usuario pida un resumen del + dia, estado general de los sistemas, o un reporte periodico. Tambien puede + activarse automaticamente via schedule. +--- + +# Reporte diario + +## Prerequisitos + +- Tool `ssh_command` para consultar estado de servicios +- Tool `http_get` para health checks +- Tool `matrix_send` para enviar el reporte a una room + +## Flujo + +### 1. Recopilar datos + +Ejecutar en paralelo cuando sea posible: + +**Estado de servicios:** +```bash +ssh_command: "systemctl list-units --type=service --state=running --no-pager | grep -E ''" +ssh_command: "systemctl list-units --type=service --state=failed --no-pager" +``` + +**Uso de recursos:** +```bash +ssh_command: "df -h / | tail -1" +ssh_command: "free -h | grep Mem" +ssh_command: "uptime" +``` + +**Errores recientes:** +```bash +ssh_command: "journalctl --priority=err --since '24 hours ago' --no-pager | wc -l" +ssh_command: "journalctl --priority=err --since '24 hours ago' --no-pager | tail -10" +``` + +**Health checks HTTP:** +``` +http_get: "/health" para cada servicio con endpoint +``` + +### 2. Formatear reporte + +Generar markdown con: + +```markdown +## Reporte diario — + +### Estado de servicios +| Servicio | Estado | Uptime | +|----------|--------|--------| +| servicio-1 | OK | 5d 3h | +| servicio-2 | FAILED | - | + +### Recursos +- **Disco**: 45% usado (55GB libres) +- **Memoria**: 3.2GB / 8GB (40%) +- **Load average**: 0.5, 0.3, 0.2 + +### Errores (ultimas 24h) +- Total: 15 errores +- Mas frecuente: "connection timeout" (8 veces) + +### Alertas +- servicio-2 esta caido desde las 14:30 +- Disco al 85% en /var/log (limpiar) +``` + +### 3. Enviar + +Enviar el reporte formateado a la room configurada o a la room donde fue solicitado. + +## Personalizacion + +El reporte puede adaptarse segun: +- Lista de servicios a monitorear (del config del agente) +- Servidores a consultar (de ssh.allowed_targets) +- Umbrales de alerta (disco > 80%, memoria > 90%, etc.) diff --git a/skills/communication/daily-report/templates/.gitkeep b/skills/communication/daily-report/templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/devops/deploy-service/SKILL.md b/skills/devops/deploy-service/SKILL.md new file mode 100644 index 0000000..d2199fc --- /dev/null +++ b/skills/devops/deploy-service/SKILL.md @@ -0,0 +1,89 @@ +--- +name: deploy-service +description: > + Despliega un servicio en un servidor remoto via SSH. Usa esta skill cuando + el usuario pida hacer deploy, actualizar un servicio, o subir cambios a + produccion/staging. Cubre: pull de codigo, build, restart del servicio, + y verificacion post-deploy. +--- + +# Deploy de servicio via SSH + +## Prerequisitos + +- El agente debe tener la tool `ssh_command` habilitada +- El servidor destino debe estar configurado en `ssh.allowed_targets` +- El usuario debe tener permisos de deploy (verificar roles si RBAC esta activo) + +## Flujo + +### 1. Confirmar parametros + +Antes de ejecutar, confirmar con el usuario: +- **Servicio**: nombre del servicio a desplegar +- **Servidor**: host destino (debe estar en allowed_targets) +- **Branch/tag**: rama o tag a desplegar (default: main) +- **Ruta**: directorio del servicio en el servidor + +### 2. Pre-checks + +Ejecutar en el servidor remoto: +```bash +# Verificar conectividad +ssh_command: "echo 'OK'" en el host destino + +# Verificar que el directorio existe +ssh_command: "test -d /path/to/service && echo 'exists'" + +# Verificar estado actual del servicio +ssh_command: "systemctl is-active nombre-servicio || true" +``` + +Si algun pre-check falla, informar al usuario y no continuar. + +### 3. Deploy + +Ejecutar secuencialmente: +```bash +# Pull de cambios +ssh_command: "cd /path/to/service && git fetch origin && git checkout && git pull" + +# Build (si aplica) +ssh_command: "cd /path/to/service && make build" +# o: "cd /path/to/service && go build -o bin/service ./cmd/..." +# o: "cd /path/to/service && docker-compose build" + +# Restart del servicio +ssh_command: "sudo systemctl restart nombre-servicio" +``` + +### 4. Verificacion post-deploy + +```bash +# Esperar 5 segundos para que el servicio arranque +ssh_command: "sleep 5 && systemctl is-active nombre-servicio" + +# Verificar logs recientes (buscar errores) +ssh_command: "journalctl -u nombre-servicio --since '1 min ago' --no-pager | tail -20" + +# Health check HTTP si aplica +http_get: "http://servidor:puerto/health" +``` + +### 5. Reportar resultado + +Informar al usuario: +- Estado del deploy (exitoso/fallido) +- Version desplegada (commit hash o tag) +- Estado del servicio post-deploy +- Cualquier warning en los logs + +## Rollback + +Si el deploy falla o el servicio no arranca: +```bash +ssh_command: "cd /path/to/service && git checkout " +ssh_command: "sudo systemctl restart nombre-servicio" +``` + +Informar al usuario que se hizo rollback y el motivo. diff --git a/skills/devops/deploy-service/scripts/.gitkeep b/skills/devops/deploy-service/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/system/health-check/SKILL.md b/skills/system/health-check/SKILL.md new file mode 100644 index 0000000..03c485d --- /dev/null +++ b/skills/system/health-check/SKILL.md @@ -0,0 +1,95 @@ +--- +name: health-check +description: > + Verifica la salud de uno o varios servicios y servidores. Usa esta skill + cuando el usuario pregunte si algo esta funcionando, si un servicio esta + arriba, o pida un chequeo de salud general. Tambien util despues de un + deploy o un incidente. +--- + +# Health check de servicios + +## Prerequisitos + +- Tool `ssh_command` habilitada +- Tool `http_get` para endpoints HTTP +- Servidores en `ssh.allowed_targets` + +## Flujo + +### 1. Determinar alcance + +Inferir del contexto del usuario: +- **Servicio especifico**: checkear solo ese servicio +- **Servidor especifico**: checkear todos los servicios en ese servidor +- **General**: checkear todos los servidores y servicios conocidos + +### 2. Checks basicos por servidor + +Para cada servidor: +```bash +# Conectividad +ssh_command: "echo OK" + +# Uptime y load +ssh_command: "uptime" + +# Disco +ssh_command: "df -h / /var /tmp 2>/dev/null | tail -n +2" + +# Memoria +ssh_command: "free -m | grep -E 'Mem|Swap'" + +# Procesos zombie o en estado D +ssh_command: "ps aux | awk '{if ($8 ~ /Z|D/) print}' | head -5" +``` + +### 3. Checks por servicio + +Para cada servicio: +```bash +# Estado systemd +ssh_command: "systemctl is-active " + +# Tiempo activo +ssh_command: "systemctl show --property=ActiveEnterTimestamp --value" + +# Puertos abiertos +ssh_command: "ss -tlnp | grep " + +# Ultimos errores +ssh_command: "journalctl -u --priority=err --since '1 hour ago' --no-pager | tail -5" +``` + +**Health check HTTP** (si tiene endpoint): +``` +http_get: "http://:/health" +``` + +### 4. Evaluar y reportar + +Clasificar cada componente: + +| Estado | Criterio | +|--------|----------| +| OK | Servicio activo, sin errores recientes, recursos normales | +| WARNING | Servicio activo pero con errores recientes, o recursos > 80% | +| CRITICAL | Servicio caido, disco lleno, o memoria agotada | + +Reportar al usuario con formato claro: +``` +Health Check — + +[OK] servidor-1: load 0.3, disco 45%, mem 40% + [OK] servicio-a: activo (uptime 5d), 0 errores + [WARNING] servicio-b: activo, 3 errores en ultima hora +[CRITICAL] servidor-2: no responde SSH +``` + +### 5. Recomendaciones + +Si hay problemas, sugerir acciones: +- Servicio caido → "Intentar restart: `systemctl restart `" +- Disco lleno → "Limpiar logs antiguos o expandir disco" +- Memoria alta → "Revisar procesos con mayor consumo" +- Errores frecuentes → "Revisar logs con la skill log-analyzer" diff --git a/skills/system/health-check/scripts/.gitkeep b/skills/system/health-check/scripts/.gitkeep new file mode 100644 index 0000000..e69de29