Una skill extraída de una conversación exitosa puede arrastrar instrucciones que solo sirven para aquella tarea. Para evaluar agent skills, prepara casos nuevos y compara al mismo agente con y sin la skill. Necesitas una sesión resuelta, acceso a sus instrucciones y un entorno donde puedas ejecutar cada prueba con contexto limpio.
El objetivo es comprobar qué parte del procedimiento se transfiere: cómo interpreta la entrada, qué decisiones toma y cómo verifica la salida. Repetir el trabajo original sirve para revisar la extracción, pero las tareas reservadas son las que ponen a prueba su reutilización.
Qué necesitas para evaluar una skill
Una Agent Skill es una carpeta con un archivo SKILL.md, que combina metadatos YAML e instrucciones Markdown. También puede incluir scripts, referencias y recursos. Según la especificación oficial, los campos obligatorios son name y description; el nombre debe coincidir con el de la carpeta.
Prepara también acceso al modelo y a las herramientas con las que ejecutarás las pruebas. Necesitas poder separar sesiones y guardar las salidas, porque una respuesta correcta sin su contexto de ejecución aporta poca información para comparar.
Distingue desde el principio qué quieres mejorar. Una skill que enseña una capacidad se evalúa por lo que consigue resolver; una que recoge el proceso de tu equipo se evalúa por su fidelidad a ese proceso. Anthropic recoge esta distinción en su guía sobre evaluación y mejora de skills.
La separación entre memoria y procedimiento también ayuda a decidir qué guardar. En el artículo sobre Hermes Agent y sus capas de memoria y skills tienes más contexto sobre esa diferencia.
1. Extrae el procedimiento de la conversación resuelta
Revisa la sesión y escribe qué recibió el agente, qué herramientas necesitó, qué pasos siguió y qué condiciones debía cumplir la salida. El skill-creator de Anthropic contempla esta extracción desde una conversación, incluidas las correcciones que llevaron al resultado.
Fuente: skills/skills/skill-creator/SKILL.md at main
Supón que la tarea consistía en transformar una tabla en JSON para otro sistema. Conserva las reglas para interpretar columnas, tratar valores incompletos y comprobar la salida. Revisa por separado los nombres de archivo, las rutas y las excepciones que aparecieron durante aquella sesión.
Una ruta fija puede pertenecer al proceso real de tu equipo. En ese caso, mantenla y explica su función. Si solo indicaba dónde estaba el archivo de aquella tarea, conviértela en una entrada que el agente deba identificar.
Redacta la skill con estas acciones:
- Describe qué problema resuelve y cuándo debe activarse.
- Especifica qué entrada necesita y qué debe revisar antes de actuar.
- Ordena los pasos que hicieron falta para resolver la tarea.
- Explica el motivo de las restricciones y las comprobaciones.
- Define qué salida debe entregar y cómo verificarla.
Al terminar, deberías poder relacionar cada instrucción con una necesidad del procedimiento. Revisa especialmente las órdenes que surgieron como reacción a un error puntual: pueden aportar una regla útil o introducir una excepción demasiado estrecha.
2. Prepara casos nuevos y reserva sus entradas
La guía oficial de evaluación propone guardar los casos en evals/evals.json, con prompt, expected_output y archivos opcionales. Recomienda empezar con dos o tres casos, variar la redacción e incluir entradas malformadas o situaciones límite.
Separa los casos que usas para redactar la skill del conjunto reservado que abrirás después de fijar sus instrucciones. Si corriges la receta cada vez que ves una entrada, esa entrada ya ha participado en su desarrollo.
Para la transformación de tablas, prepara casos con diferencias que puedas interpretar:
| Caso | Qué cambias | Qué compruebas |
|---|---|---|
| Columnas distintas | Renombras encabezados y cambias su orden | El agente interpreta los campos sin depender de su posición original |
| Entrada malformada | Introduces registros incompletos | Aplica el tratamiento previsto sin inventar valores |
| Restricción nueva | Cambias el formato de salida solicitado | Sigue las condiciones actuales sin arrastrar el formato anterior |
Define el resultado esperado antes de ejecutar. Para los campos, especifica la correspondencia correcta; para los registros incompletos, indica qué tratamiento exige la tarea. Si admites varias respuestas válidas, escribe los criterios que comparten.
No cambies todos los detalles a la vez. Un caso que modifica rutas, estructura y restricciones puede detectar un fallo, pero después tendrás que aislar qué cambio lo provocó.
3. Congela la skill y compara ambas configuraciones
Guarda una copia identificable de la skill antes de abrir los casos reservados. La especificación admite registrar una versión mediante metadata, aunque ese campo es opcional. Esa copia será la que evalúes durante toda la comparación.
Ejecuta cada caso con el mismo prompt y los mismos archivos, primero en una configuración y después en la otra. Mantén el modelo, las herramientas y los permisos; la diferencia que quieres estudiar es la presencia de la skill.
La condición más importante es el contexto limpio. Usa sesiones separadas, sin la conversación de desarrollo ni los resultados de pruebas anteriores. Si el agente ya ha visto la solución, introduces una ayuda que contamina la comparación.
El procedimiento queda así:
- Abre una sesión nueva sin la skill y ejecuta el caso.
- Guarda la salida, las evidencias disponibles y los datos de consumo.
- Abre otra sesión nueva con la copia congelada de la skill.
- Ejecuta el mismo caso y guarda los mismos datos.
- Anota si la skill se activó antes de puntuar el resultado.
Deberías acabar con dos ejecuciones comparables por caso. Conserva también los errores de herramientas y los bloqueos por permisos: ayudan a distinguir un problema del procedimiento de otro del entorno.
4. Comprueba resultados, tiempo y tokens
Evalúa condiciones observables. «La respuesta parece mejor» deja demasiado margen al gusto; «el JSON es válido y conserva los registros exigidos» identifica algo que puedes comprobar y documentar.
Para condiciones mecánicas, la guía oficial recomienda scripts de verificación. Puedes comprobar el formato, los campos obligatorios o los recuentos. Para decisiones que requieren criterio, utiliza revisión humana y, cuando sea posible, comparación ciega sin saber qué configuración produjo cada respuesta.
Registra los aciertos, tiempo y tokens junto con las evidencias. Una skill puede mejorar la fidelidad al procedimiento y consumir más recursos; esa diferencia te ayuda a decidir si encaja en tu trabajo. Si ya estás revisando el consumo de agentes, el artículo sobre los límites de Claude Code aporta contexto para esa decisión.
Si trabajas con el entorno de skill-creator, su documentación incluye este comando para agregar las evaluaciones desde el directorio de la herramienta:
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>Sustituye los marcadores por el directorio de tu evaluación y el nombre de tu skill. El comando produce benchmark.json y benchmark.md con resultados por configuración.
Repite los casos si quieres estudiar la variabilidad. La guía advierte de que la desviación estándar solo aporta información significativa con varias ejecuciones por caso; una respuesta aislada sirve para inspeccionar un fallo, pero no describe su frecuencia.
5. Retira instrucciones para descubrir qué aportan
Localiza las instrucciones relacionadas con los fallos o con pasos que el agente ya resolvía sin ayuda. Retira una cada vez y vuelve a ejecutar los casos afectados con contexto limpio. Mantén una copia de cada variante para poder atribuir el cambio.
Empieza por órdenes ligadas al caso original: rutas concretas, nombres de columnas, formatos fijos o pasos obligatorios cuyo motivo no está explicado. Si una instrucción no cambia los resultados, márcala para revisión; si al retirarla aparece un fallo, conserva la evidencia que justifica mantenerla.
Revisa también el orden de las acciones. Vercel documentó un caso donde ordenar consultar primero una skill produjo un page.tsx correcto, pero dejó pendientes cambios en next.config.ts. Explorar primero el proyecto y consultar después la skill resolvió ambas partes en su evaluación de agentes.
Cuando incorpores un fallo a tus ejemplos de desarrollo, prepara otro caso reservado para la siguiente evaluación. Así evitas seguir midiendo únicamente tareas cuyas soluciones ya han influido en las instrucciones.
Fallos frecuentes: activación, rigidez y contexto heredado
Separa los fallos de activación de los fallos de ejecución. Si el agente nunca consulta la skill, revisa su descripción: una demasiado estrecha puede impedir su uso y una demasiado amplia puede activarla donde no corresponde.
Ese problema tuvo peso en el experimento de Vercel sobre Next.js 16: la skill no se invocó en el 56 % de los casos y obtuvo el mismo 53 % de aciertos que la configuración sin documentación. Con instrucciones explícitas llegó al 79 %. Son resultados de aquel experimento, útiles para justificar que registres la activación como una comprobación independiente.
Si la skill se activa pero falla al cambiar las entradas, revisa las suposiciones heredadas. Sustituye posiciones fijas por criterios para identificar campos, explica cómo actuar ante datos incompletos y elimina formatos impuestos que contradigan la petición actual. Después repite la comparación.
Ojo con reutilizar el chat donde redactaste la skill: el agente puede apoyarse en correcciones que nunca llegaron a SKILL.md. Ejecuta el próximo caso reservado en sesiones nuevas, guarda ambas salidas y comprueba primero si la skill se activó; después puntúa si resolvió la tarea.
¿Qué te ha parecido?
Déjame tu opinión, pregunta o sugerencia. Los comentarios se sincronizan con GitHub Discussions .