Cuando una alarma salta a las dos de la mañana, la calidad de la investigación depende de quién esté de guardia. Quien construyó el servicio sabe qué mirar primero y qué umbral indica un problema; quien no, reconstruye ese conocimiento cada vez. AWS DevOps Agent, el agente de operaciones de AWS que investiga incidentes, busca cerrar esa brecha con Skills. Un Skill es una carpeta de instrucciones que el agente carga solo cuando la tarea coincide con la descripción asociada.

La guía de AWS, publicada el 30 de septiembre de 2026 por Nisha Notani y Damini Kumar, describe dos condiciones. Un Skill falla si el agente no lo carga a tiempo o si no encuentra dentro una investigación que pueda seguir. El contenido importa, pero llega después: uno bien escrito convierte el conocimiento del equipo en un procedimiento reutilizable; uno mal escrito se ignora por completo.

La descripción decide si el Skill se carga

El agente evalúa la descripción antes de leer las instrucciones. Una descripción vaga hace que el agente descarte el Skill aunque el archivo sea excelente, y la guía considera ese campo el área de mayor impacto.

Conviene escribirla desde la perspectiva del agente, con los servicios, tipos de error, síntomas y alarmas que deberían disparar la carga. Si la descripción no permite saber si el Skill aplica, faltan nombres concretos.

La guía relata un caso. Un Skill llamado db-health declaraba "Monitors database health". Cuando una base de datos de Amazon RDS, el servicio relacional de AWS, agotó sus conexiones, el agente no lo cargó. Nada en esa frase coincidía con la alarma RDS-DatabaseConnections-Critical.

El equipo reescribió la descripción como "Investigation procedures for RDS connection exhaustion, max_connections breaches, and DatabaseConnections alarm spikes", y el nombre y las instrucciones no cambiaron. Desde entonces el agente lo carga cada vez que esa alarma se dispara.

Las instrucciones son pasos de investigación

Un Skill útil no enumera datos: encadena comprobaciones. Cada paso debe decir qué revisar, qué señal observar y a dónde ir según el hallazgo.

La guía contrasta dos versiones de un Skill de contenedores. La primera lista tareas, procesador, memoria y despliegues recientes sin secuencia, umbrales ni puntos de decisión: no hay forma de saber qué está mal ni qué hacer. La segunda clasifica el patrón de fallo.

Un código de salida 137, que indica falta de memoria, enruta a un paso sobre límites de memoria. Una salida con error de contenedor esencial enruta a dependencias, y una comprobación de estado fallida, a tiempos de arranque.

Ese es el patrón: acción concreta, señal específica y una decisión que conduce al paso siguiente. Las tablas de umbrales sirven como archivo de referencia; el SKILL.md debe contener la lógica que las usa.

Skill o instrucción permanente: cuándo se carga cada una

Las instrucciones de agente, guardadas en un archivo AGENTS.md, se aplican en todas las sesiones. Los Skills se leen solo cuando su descripción coincide con la tarea en curso.

Esa diferencia basta para decidir. Lo que debe regir todas las investigaciones, como el formato de respuesta o una política de seguridad, va en las instrucciones. Un procedimiento para un escenario concreto, como investigar el agotamiento de conexiones, va en un Skill.

El tamaño refuerza la separación. Un AGENTS.md, el archivo de políticas permanentes del agente, tiene un límite duro de 25 KB y una recomendación de unas 120 líneas. Compite por el espacio de las preguntas, los registros y el razonamiento, así que un archivo que intenta contenerlo todo resta espacio a todo lo demás.

Elegir el tipo de agente también ahorra contexto. Un Skill puede dirigirse a un tipo concreto, como la clasificación, el análisis de causa o la mitigación, para no cargar una guía de remediación mientras el incidente se clasifica. Conviene empezar con el tipo genérico.

Referencias, memoria y composición

El SKILL.md, el documento Markdown con la descripción y los pasos, guarda la lógica. Los archivos de referencia guardan el conocimiento que esa lógica necesita: tablas de umbrales, mapas de códigos de error y la arquitectura de dependencias.

Los hechos que cambian rápido, como qué servicios dependen de cuáles, van a la memoria del agente y se actualizan sin editar el Skill. Esa separación frena el deterioro: lo que más se desactualiza deja de vivir en el procedimiento.

La composición amplía el patrón. El agente puede leer varios Skills en una misma investigación, así que cada uno debe ser útil por separado. Un Skill que cubre todo un servicio falla por partida doble: su descripción no puede ser específica y su tamaño deja de ser eficiente.

Lo mismo vale para herramientas externas. Un Skill puede documentar cómo usar cada herramienta MCP (Model Context Protocol, el estándar que conecta herramientas de diagnóstico): cuándo invocarla y cómo interpretar el resultado. Sin esa guía, el agente sabe que existe, pero no cómo usarla.

Los fallos que aparecen con el tiempo

Los fallos importantes aparecen después. La guía señala cuatro.

  • Skills que se contradicen. Dos Skills pueden dar instrucciones opuestas en el mismo incidente: uno pide ampliar las conexiones y otro reducirlas. Antes de publicar uno nuevo, conviene revisar qué otros apuntan a las mismas alarmas y explicitar su límite.
  • Skills que envejecen sin avisar. Un Skill puede citar recursos que ya no existen. A diferencia del código, no falla de forma ruidosa: produce hallazgos irrelevantes. La guía recomienda revisarlos cada trimestre, como un runbook (un procedimiento operativo escrito), y anotar la fecha de la última verificación.
  • Pasos demasiado rígidos. Una secuencia estricta atrapa al agente cuando el incidente no sigue el patrón. Si el primer paso devuelve resultados normales, debe existir una salida hacia la investigación general, en lugar de completar los pasos y declarar que todo está bien.
  • Skills duplicados. Varios miembros del equipo escriben Skills solapados y el agente hace trabajo redundante. Un inventario de Skills, alarmas y servicios permite detectar el solapamiento.

Por dónde empezar

La guía propone un punto de partida: las tres categorías de incidentes más frecuentes del último trimestre. Para cada una, conviene preguntar al ingeniero sénior que suele resolverla qué comprueba primero. Esa respuesta es el paso uno; la siguiente pregunta, qué distingue un caso de otro, completa el flujo. Un SKILL.md de 20 líneas con pasos claros rinde más que uno de 200 con orientación vaga.

La guía completa está en Best practices for writing AWS DevOps Agent Skills (AWS Cloud Operations Blog, 30 de septiembre de 2026), de Nisha Notani y Damini Kumar: https://aws.amazon.com/blogs/mt/best-practices-for-writing-aws-devops-agent-skills/