Analicé 300 registros de fallos de agentes. El problema nunca fue el prompt.

Trescientos registros de fallos de agentes. Los revisé durante dos semanas, etiquetando cada uno según la causa raíz. Los resultados me sorprendieron: los problemas de prompt representaban quizás un 12%. ¿El resto? El contexto estaba contaminado, desbordado o directamente ausente. Cambiar de modelo no ayudó. Cambiar de herramientas tampoco. El patrón se repetía sin excepción.

Llevo tiempo profundizando en context engineering, así que cuando apareció un proyecto de código abierto llamado Agent Skills for Context Engineering y cruzó rápidamente las 10.000 estrellas en GitHub, le presté atención. Tiene licencia MIT, lo ha construido un context engineer llamado Muratcan Koylan, y está citado en un paper de un laboratorio de IA de la Universidad de Pekín. Ese último detalle fue lo que me hizo clonarlo de verdad.

Los contextos más pequeños son más precisos

Yo asumía que meter más tokens en el contexto siempre ayudaría. Me equivocaba. El primer principio que enseña este skillset es “densidad de información, no volumen de información”.

A medida que el contexto crece, los modelos pierden de vista lo que hay en el medio. Es el efecto de curva en U: el modelo lee bien el principio y el final, pero se salta todo lo que queda entre medias. Lo comprobé yo mismo llenando el contexto hasta 128K tokens y luego comprimiendo la misma información a 32K. La versión comprimida obtuvo mejor puntuación en precisión.

El coste de procesamiento no escala linealmente con el número de tokens; crece de forma exponencial. Reducir el contexto a la mitad acortó la latencia de respuesta entre un 40 y un 60 por ciento. Incluso con prefix caching, los inputs largos siguen siendo caros. El resumen en una línea: lo que importa es cuánta información útil puedes meter en un presupuesto de tokens determinado.

Las descripciones de las herramientas determinan el 80% del rendimiento del agente

Puedes escribir un prompt perfecto, pero si las descripciones de tus herramientas son descuidadas, el agente elegirá la herramienta equivocada. Este skillset lo plantea muy bien: “Las herramientas son contratos que leen los LLMs, no las personas.” Cuando mi equipo construyó un servidor MCP, reescribimos las descripciones de nuestras herramientas siguiendo esta guía. Los fallos en la selección de herramientas se redujeron de forma notable.

Cada descripción de herramienta debe especificar cuándo usarla y qué devuelve. Cuando dos herramientas se solapan en funcionalidad, los humanos se confunden, y los agentes se confunden todavía más. Una herramienta completa suele ser mejor que varias específicas y limitadas. Y los mensajes de error deben indicar al agente qué hacer a continuación, no solo qué ha salido mal.

Los sistemas multi-agente necesitan arquitectura antes que agentes

Lanzar varios agentes y esperar que colaboren de forma automática es pura ilusión. El repositorio define tres patrones con claridad: un orquestador que dirige agentes subordinados, un modelo peer-to-peer donde los agentes se comunican como iguales, y una cadena de delegación jerárquica.

Tras probar los tres en producción, el patrón de orquestador fue el más predecible y el más fácil de depurar. Los agentes subordinados pasaban resultados a través del sistema de ficheros. El modelo peer-to-peer funcionó mejor para tareas creativas, pero corría el riesgo de bucles infinitos. Para consultas estructuradas, los ficheros compartidos superaban a la búsqueda vectorial. En la práctica, tres agentes fue el límite de estabilidad.

La búsqueda vectorial sola no puede gestionar la memoria

La búsqueda vectorial encuentra fácilmente “El cliente X compró el producto Y en la fecha Z”. No puede responder a “¿Qué más compraron los clientes que adquirieron el producto Y?” La información relacional se pierde en los embeddings.

El skillset propone una arquitectura de memoria en cuatro niveles: memoria de trabajo dentro de la ventana de contexto, memoria a corto plazo dentro de una sesión, memoria a largo plazo entre sesiones, y memoria permanente como archivo. El patrón de sistema de ficheros como memoria fue el más práctico de los que probé. Navegas el contexto con ls y grep en lugar de consultas de embeddings. Volcar los resultados de las herramientas en un fichero scratchpad ahorró un espacio considerable en la ventana de contexto.

La evaluación es la habilidad más infravalorada en agentes

Esta fue la sección que estuve a punto de saltarme, y resultó ser la más valiosa. El repositorio incluye un framework de evaluación en TypeScript que usa LLMs como jueces. Incluso genera automáticamente rúbricas de puntuación.

Lo que me impresionó fue la mitigación del sesgo posicional. Al comparar dos respuestas en paralelo, el framework evalúa dos veces con el orden invertido. Esto contrarresta la tendencia a valorar más favorablemente la respuesta que aparece primero. Soporta tanto puntuación directa como comparación por pares. Construir un pipeline de evaluación significó que por fin podía medir si los cambios en los prompts mejoraban realmente el rendimiento, en lugar de adivinarlo.

Una cosa que el repositorio no resuelve: las rúbricas de evaluación siguen necesitando calibración humana. Las rúbricas generadas automáticamente ofrecen puntos de partida razonables, pero tuve que ajustar los pesos de puntuación para mi dominio específico antes de que los resultados fueran fiables.

Cuando tu agente se equivoca, revisa el contexto antes de culpar al modelo. El repositorio está aquí.