Testing Your AI Agent Skills
Testing Your AI Agent Skills debe ser el primer paso después de escribir un SKILL.md. Si no tienes una suite de evals automatizados, lo que hoy llamas “skill” es un prototipo frágil: funciona en local tres veces y falla en producción cuando más importa. Aquí explico cómo pasar de sensaciones a ingeniería sólida, con ejemplos prácticos, métricas y scripts que puedes integrar hoy mismo.
Tiempo estimado de lectura: 4 min
- Automatiza evals: una skill sin evaluación automatizada es frágil; integra graders deterministas y repite trials.
- Métricas claras: mide capacidad (pass@k), fiabilidad (pass^k) y correctitud (grader determinista con exit codes).
- Aislamiento: usa Docker para cada trial y destruye el entorno tras la verificación.
- Repetición: ejecuta >=5 trials para estimar estabilidad; optimiza para pass^k alto antes de producción.
Testing Your AI Agent Skills: por qué importa y qué mide un eval
Una Skill no es un prompt bonito: es documentación ejecutable que un agente usa para actuar. Cambiar una instrucción, reordenar pasos o quitar una verificación puede romper el comportamiento sin avisos. Los LLMs son no deterministas; una ejecución exitosa no prueba nada. Los evals automatizados solucionan eso midiendo tres cosas:
- Capacidad (pass@k): ¿puede el agente resolver la tarea al menos una vez en k intentos?
- Fiabilidad (pass^k): ¿la resuelve todas las veces en k intentos?
- Correctitud (grader determinista): ¿el resultado cumple la condición objetiva (compila, lint pasa, tabla creada)?
Un ejemplo realista de comando que debes poder ejecutar en CI:
GEMINI_API_KEY=your-key npm run eval superlint -- --provider=docker --trials=5Eso encapsula aislamiento (Docker), repetición estadística (trials) y la unidad de test (la skill superlint).
Repositorio de referencia: https://github.com/mgechev/skill-eval
Arquitectura mínima de un eval efectivo
Cada tarea debe ser autocontenida y reproducible. Estructura sugerida:
tasks/my_task/
├── task.toml # timeouts, recursos, límites
├── instruction.md # el prompt único para el agente
├── environment/Dockerfile
├── tests/test.sh # grader determinista (shell)
├── prompts/quality.md # grader de rúbrica (opcional)
├── solution/solve.sh # referencia
└── skills/my_skill/
└── SKILL.mdPrincipios clave:
- El agente recibe solo
instruction.mdcomo prompt primario. Las skills viven en rutas de descubrimiento estándar (.agents/skills/o.claude/skills/). - Los graders deterministas deben ser código: scripts que ejecutan
eslint,npm testo consultas SQL y devuelven PASS/FAIL. - Usa Docker para aislar cada trial y destruir el contenedor tras la verificación. Documentación Docker: https://www.docker.com/
Ejemplo práctico: verificador determinista para superlint
Si la tarea es “arreglar errores de lint”, el grader no puede ser subjetivo. Un ejemplo de tests/test.sh:
#!/usr/bin/env bash
set -e
# Ejecuta eslint en la ruta de trabajo
npx eslint main.js --max-warnings=0
if [ $? -eq 0 ]; then
echo "PASS"
exit 0
else
echo "FAIL"
exit 1
fiNo preguntes al LLM “¿lo hiciste bien?”. Ejecuta eslint (https://eslint.org) y deja que el exit code decida.
Repetición y métricas: por qué 5 trials no es arbitrario
Los LLMs introducen variabilidad. Ejecutar 5 trials te da una muestra mínima para estimar estabilidad. Interpretación práctica:
pass@5 = 100%ypass^5 = 100%→ listo para producción.pass@5 = 100%ypass^5 = 30%→ el agente puede hacerlo, pero es flaky; no desplegar.pass@5 < 80%→ la skill necesita rediseño (más contexto, scripts deterministas, aclaraciones en SKILL.md).
Para workflows críticos (migraciones, despliegues), fija umbral >= 90% pass^k.
Integración CI: Quality Gate para Skills
Añade un job que corra los evals en cada PR que toque skills/ o tasks/:
name: Skill Eval
on:
pull_request:
paths: ['skills/**', 'tasks/**']
jobs:
eval:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: GEMINI_API_KEY=${{ secrets.GEMINI_API_KEY }} npm run eval my_task -- --trials=5 --provider=dockerSi la tasa de éxito cae por debajo del umbral, el PR queda bloqueado con el output del eval (trials individuales, logs, grader output). Esa transparencia es crítica para debugging rápido.
Diagnóstico accionable cuando fallan trials
Un buen eval no solo marca FAIL; explica por qué. Ejemplo de salida útil:
Trial 1: FAIL - Agent ran 'eslist --lint' (typo)
Trial 2: PASS
Trial 3: FAIL - Agent modified src/utils.js instead of src/main.js
Trial 4: PASS
Trial 5: PASSCon esa trazabilidad ajustas SKILL.md o scripts (p. ej., forzar paths absolutos, añadir checks previos, mejorar error handling en scripts).
Recomendaciones finales y checklist rápido
- Mantén
SKILL.mdcorto y prescriptivo; externaliza lo frágil ascripts/. - Usa Docker para todos los evals que toquen filesystem o red.
- Implementa graders deterministas como contrato (stdout JSON + exit codes).
- Ejecuta >=5 trials; optimiza para
pass^ken producción. - Integra evals en CI como Quality Gate.
- Mantén dataset de pruebas realistas (repos con edge-cases), no solo ejemplos sintéticos.
Testing Your AI Agent Skills no es opcional. Si confías en agentes para tocar código o infra, mide su comportamiento bajo condiciones reproductibles. Implementa evals hoy y transforma tus skills de “probablemente funcionan” a “sabemos que funcionan”.
Como continuación lógica a estos procesos y para explorar integraciones y experimentos prácticos con evaluaciones de skills y pipelines de CI, visite Dominicode Labs. Allí encontrará recursos y ejemplos orientados a equipos de ingeniería que automatizan agentes y workflows.
FAQ
- ¿Qué es un eval para una Skill?
- ¿Cuántos trials debo ejecutar?
- ¿Por qué usar Docker en cada trial?
- ¿Cómo debe devolver resultados un grader?
- ¿Qué hacer si pass@k es alto pero pass^k es bajo?
- ¿Qué umbral usar en producción?
Un eval es una prueba autocontenida y reproducible que ejecuta una skill contra un grader determinista para verificar comportamiento objetivo (por ejemplo, lint pasa, tests verdes, tabla creada).
Ejecuta al menos 5 trials para estimar estabilidad. Ese número proporciona una muestra mínima para analizar variabilidad en LLMs.
Docker aísla el entorno, evita efectos laterales entre trials y garantiza reproducibilidad. Además permite destruir el contenedor tras la verificación.
Como código: exit codes y stdout estructurado (por ejemplo JSON). Evita evaluaciones subjetivas; usa herramientas como eslint o npm test.
No desplegar. Señala que la skill es flaky; mejora el prompt, agrega verificaciones adicionales o externaliza pasos frágiles a scripts deterministas.
Para workflows críticos, fija umbral ≥ 90% en pass^k. Ajusta según riesgo y gravedad del fallo.
