Skills de IA para analizar logs: cómo estructuré un diagnóstico reproducible

Cómo diseñé un conjunto de skills y agentes para asistentes de IA que detectan la tecnología de un log, piden el contexto que falta y entregan un diagnóstico estandarizado. Diseño, instalación y límites.

Resumen

Analizar logs con un asistente de IA funciona mejor cuando el asistente sigue un procedimiento en lugar de improvisar. Reuní mis instrucciones en ia-tools: una colección de skills y agentes, en español, para Claude Code, Codex y otros entornos compatibles con el estándar abierto Agent Skills.

Este artículo explica cómo están diseñados, por qué los dividí así y qué límites tienen.

El problema

Pegar un stack trace en un chat y preguntar "¿qué está fallando?" da resultados dispares:

• El asistente supone la tecnología y la versión sin preguntar.
• Cada respuesta tiene un formato distinto, difícil de comparar o de pasar a un ticket.
• Los datos sensibles (tokens, credenciales, datos personales) se cuelan sin que nadie los señale.
• El diagnóstico ocurre sin conocer el entorno (producción o desarrollo, rol del servidor, versión).

Un buen diagnóstico siempre sigue los mismos pasos. Y si los pasos son siempre los mismos, se pueden escribir una sola vez.

Qué es una skill

Una skill es una carpeta con un archivo SKILL.md: instrucciones que el modelo carga automáticamente cuando la conversación coincide con su description, o que invocas a mano con /nombre. El material de referencia largo vive en references/ y se carga solo cuando hace falta.

Esa carga bajo demanda es la decisión de diseño más importante: no meter todo en el contexto. Una sola skill gigante con reglas para veinte tecnologías consumiría contexto y diluiría las instrucciones.

Cómo está organizado

Una skill principal y varias específicas por tecnología:

• log-analyzer: detecta la tecnología del log a partir de sus patrones, pide el contexto que no puede inferir y produce un diagnóstico estandarizado.
• Skills por familia técnica: nube (Azure, AWS, GCP), bases de datos (PostgreSQL, Oracle, SQL Server), Docker, .NET, Kafka, Kubernetes y OpenShift, Laravel, PHP, Spring Boot, Quarkus, servidores web, Windows Event Log, MinIO, IBM API Connect y alertas de SRE.

La principal decide qué referencia cargar. Así el asistente trae al contexto solo lo relevante para ese log.

El flujo del diagnóstico

1. Detectar la tecnología a partir de los patrones del propio log.
2. Preguntar lo que no puede inferir: entorno, versión, rol del servidor. Diagnosticar sin ese contexto lleva a conclusiones seguras de sí mismas y equivocadas.
3. Analizar con las referencias específicas de esa tecnología.
4. Entregar un reporte con estructura fija, para que sea comparable entre incidentes y fácil de adjuntar a un ticket.

Una decisión deliberada: señalar, no ocultar

Las skills no censuran las credenciales, los tokens ni los datos personales que aparecen en el log. Los señalan en rojo en el reporte.

La razón es práctica: si el log contiene un secreto, lo que necesitas es rotarlo, y para eso tienes que saber que está ahí. Ocultarlo en silencio te deja con una falsa sensación de seguridad. El costo es que el reporte puede contener datos sensibles, así que debes revisarlo antes de compartirlo.

Una regla complementaria: no pegues logs de producción en herramientas externas sin la autorización de tu organización.

Agentes: otra pieza distinta

Además de las skills, el repositorio incluye cuatro agentes para Claude Code (roles independientes con instrucciones propias):

• Redacción de comunicaciones corporativas.
• Conversión de notas o transcripciones en minutas de reunión.
• Extracción de decisiones, tareas y riesgos accionables.
• Traducción, corrección y ajuste de tono.

Son plantillas genéricas escritas para equipos hispanohablantes; la idea es que las adaptes a tu organización.

Instalación

En Claude Code, como plugin:

/plugin install ia-tools --marketplace ifirestone/ia-tools

Para Codex y otros entornos compatibles, el repositorio incluye un script que enlaza cada skill en tu directorio de skills:

./scripts/link-skills.sh

Como son enlaces simbólicos al repositorio, un git pull mantiene todo al día. Ten en cuenta que el script reemplaza las carpetas existentes con el mismo nombre de skill, así que revísalo antes si ya tienes skills propias.

ChatGPT no tiene un mecanismo nativo para cargar skills: puedes pegar el contenido de un SKILL.md como instrucciones de un Project o de un GPT personalizado y subir las referencias como archivos de conocimiento.

Límites que conviene tener claros

• Un diagnóstico es una hipótesis, no un veredicto. El asistente puede equivocarse, sobre todo con logs parciales o sin contexto. Verifica antes de actuar.
• La calidad depende del log que le des. Un fragmento sin la línea del error raíz produce conclusiones débiles.
• Mantenimiento. Las tecnologías cambian de versión y de mensajes de error; las referencias hay que mantenerlas al día.
• Sensibilidad de los datos. Señalar no es proteger. La responsabilidad de no exponer información sigue siendo tuya.

Lo que aprendí al diseñarlo

• Un procedimiento fijo vale más que un prompt ingenioso. La consistencia es lo que vuelve útil el diagnóstico.
• Preguntar antes de diagnosticar evita la mayoría de las respuestas falsamente seguras.
• Dividir por tecnología mantiene el contexto pequeño y las instrucciones precisas.
• Escribir en el idioma del equipo reduce la fricción cuando el reporte lo lee gente de operaciones o de soporte.

Conclusión

Las skills convierten una buena práctica de diagnóstico en algo repetible y compartible. No reemplazan el criterio del ingeniero; ahorran el trabajo mecánico del primer análisis.

El repositorio es de código abierto (MIT). Si agregas una skill para otra tecnología, la guía de contribución explica la estructura.