Coding Agentes: Agent Skills

Serie de artículos sobre funcionalidades para inyectar contexto en los coding agents:

A día de hoy poco hay que decir de las Agent Skills. Tras el boom habitual de todo lo tiene que ver con los LLM pasaron a ser una funcionalidad más.

Aún así, en este artículo, vamos a repasar algunos aspectos que creo que ayudan a decidir que técnica usar para inyectar la dynamic memory en el contexto en base a cómo funciona el harness (antes llamado coding agents).

¿Estándar?

Las Skills son un estándar que no es estándar.

Básicamente son un directorio que dentro tiene un fichero llamado SKILL.md con dos propiedades de frontmatter obligatorias: name y description. El harness mantiene esas propiedades en el contexto durante toda la sesión y el LLM decide cuando invocar la skill. En ese momento se inyecta en el contexto el fichero completo de SKILL.md, el LLM sigue las instrucciones en él o pide cargar scripts u otros ficheros que vengan empaquetados con la skill.

La idea es brillante porqué es sencilla y encaja bien en las capacidades crecientes de los LLM. Pero si profundizamos vienen los problemas:

El directorio de skills no es estándar. La mayoría de harness es compatible con .agents/skills y ~/.agents/skills/, pero no todos
Los harness usan sus propias propiedades no estándar de frontmatter para definir comportamientos importantes. Por ejemplo, Claude y Cursor soportan disable-model-invocation, que no envían la descripción al contexto, y SKILL.md sólo se inyecta bajo invocación manual. Pero ni Antigravity ni OpenCode la reconocen. Y Codex la llama allow_implicit_invocation aunque haga lo mismo. Esta es una propiedad muy importante para poder organizar la documentación y prompts reutilizables cómo skills pero sin cargar el contexto
La relación de skills (sub) agentes, tools y permisos es implementada por cada harness de forma distinta
La inyección extra de contexto desde SKILL.md tampoco es estándar. Cómo se interpreta la @, el soporte para argumentos y substituciones, shell substitution, ... dependen del harness.
Las dependencias de los scripts son confusas. Cuando la skill incluye dependencias escritas en Python (o en cualquier ecosistema que no incluya el binario directamente) que pasa con las dependencias. ¿Usa el virtualenv si hay uno?, ¿entiende que yo quiero que use uv?, ¿instala a nivel sistema o de proyecto?, ...

Al final, para usar estas características que dan un montón de capacidades extra tienes que ligarte muy fuerte a un harness.

Skills vs Documentación

Las Skills nacieron como un sistema de empaquetado. Sin más. Los modelos no estaban entrenados en ellas, ni había RL, ni el harness le daba un tratamiento demasiado especial (llega con ver el historial de git de cualquier herramienta abierta).

Así que, en mi opinión, no había mucha diferencia entre tener una skill y tener un .md que referenciara otros documentos o scripts, si en la conversación o en el AGENTS.md se orientaba al LLM a consultar ese .md.

Pero en la actualidad, a pesar de que no he encontrado datos, seguro que los labs usan RL para las Skills.

Y el harness, además de las funcionalidades adicionales comentadas antes, también incluye mucha lógica para gestionarlas.

Un prompt cómo este en la versión actual de harness abiertos cómo opencode y codex da pistas interesantes.

Estoy investigando como funcionan las skills en distintos coding agents

Mi objetivo principal es determinar si hay diferencias reales entre usar skills e inyectar contexto en el modelo de forma manual, por ejemplo referenciando documentos con `@`

Por ejemplo quiero saber:

- Al usar skills en algún momento "se descargan" para reducir el contexto
- Se priorizan las instrucciones de las skills de alguna forma desde el harness / coding agents
- Que efecto tienen propiedades cómo `disable-model-invocation` o `allow_implicit_invocation` a la hora de cargar contexto

Investígalo y haz un informe. Luego trabajaremos en resolver más dudas.

En Codex:

Las instrucciones de las skills se introducen entre tags <skill>, son priorizadas por el system prompt, y se insertan al final del mensaje (aumentando la atención del LLM)
El catálogo de skills (metadata) consume un máximo del 2% del contexto. Si ocupa más lo resume
Las Skills
- son interpretadas cómo "reglas de comportamiento de agente"
- reciben un tratamiento especial en la compactación
- Se cargan al inicio del turn, y se mantienen en la sesión, pero se le pasa un prompt especial al LLM que las minusvalora "Do not carry skills across turns unless re-mentioned."
- Prioridad: Muy Alta. Casi reglas de sistema
Los documentos citados (@)
- Son interpretados de forma muy similar a mensajes del usuario
- Se compactan cómo cualquier otro elemento de la conversación
- Se cargan al inicio del turn y se mantienen en la conversación
- Prioridad: Alta. Cuando se mencionan están en la zona de atención pero su prioridad va bajando
Los documentos descubiertos (busca la documentación de testing)
- son el resultado de una tool call (ie read_file) es decir son código/datos a procesar
- Los resultados de tools son el contexto más susceptible a ser descartado en la compactación
- Se cargan en un momento no determinado y el texto se conserva cómo resultado de una herramienta.
- Prioridad: Media - Alta. Su prioridad baja muy rápido

En opencode el comportamiento es muy similar.

Conclusiones

Texto copiado (casi) directamente del LLM:

Usa inyección manual (@) para adjuntar datos específicos de la tarea actual que solo se necesitan en los próximos 2 o 3 turnos (ej. un archivo de log, un fragmento de código que quieres refactorizar, o una especificación puntual).
Usa Skills para inyectar guías de estilo, flujos de trabajo de desarrollo complejos (ej. depuración de accesibilidad, convenciones para los tests), o cualquier conjunto de instrucciones reutilizables a lo largo de toda una sesión de desarrollo larga. Su diseño bajo demanda (lazy-loaded) evita el desperdicio de tokens y las protege frente a la compactación del contexto.
Permite el descubrimiento autónomo por el LLM (el LLM descubre solo el documento) para tareas exploratorias donde no estás seguro de si existe documentación aplicable o dónde está guardada en el workspace, permitiendo que el agente busque libremente pagando el coste de algunos turnos de búsqueda iniciales
Incita al LLM a buscar un documento específico (por ejemplo, diciendo "busca la documentación de testing y después escribe los tests") cuando sabes que existe una especificación o guía útil en el workspace pero no quieres adjuntarla de golpe con @ (para evitar el eager loading de tokens) ni quieres que el agente pierda turnos divagando o buscando a ciegas.

Porqué no tengo muchas skills

En mi caso, tengo muchas "instrucciones" cómo ficheros de documentación que no he convertido a skills. Hay varios motivos, los principales:

La mayoría de esa documentación no debe ocupar contexto, ni siquiera el mínimo, porqué es para casos concretos y no todos los agentes soportan disable-model-invocation, y en todo caso, si se usa esa propiedad se pierde en parte el sentido de auto-uso del skill
En el momento en que empiezas a escribir skills es fácil engancharte a las características de un harness concreto.
La organización de información en base a skills es penosa.
- Mi docs/testing.md no es sólo para el LLM es también para los humanos
- La forma de escribirlo es distinta cuando es exclusiva para humanos, de cuando es exclusiva para agentes y mantener dos ficheros (.agents/skills/testings/SKILL.md y docs/testing.md) no es buena idea.
- Cuando tienes mucha documentación no es lo mismo tener docs/front/tests.md y docs/back/tests.md, más todos los demás documentos que una carpeta plana con .agents/skills/front-tests/SKILL.md, .agents/skills/back-tests/SKILL.md, ...
En mi forma de usar el LLM, tener documentación y no skills me ha funcionado relativamente bien.

Las conclusiones de las conclusiones

Estamos ante una tecnología muy nueva, en constante cambio
Hay mucha diferencia de comportamiento y necesidades si el agente se usa en sesiones muy dirigidas o en estilo ralph
Cada vez va a ser más importante desarrollar capacidades en torno a realizar evals para tu base de código y forma de trabajo. Más importante, que conocer el framework web o todas las características de tu lenguaje de programación.