Lo esencial
Una skill (habilidad) sin pruebas es como contratar a un cocinero y nunca probar sus platillos. A lo mejor cocina de maravilla. A lo mejor le pone sal en lugar de azúcar. Un eval es un sistema de degustación: toma la skill, la pasa por escenarios reales, da una calificación precisa y muestra exactamente dónde algo salió mal. Una skill con un pass rate bajo se puede mejorar bastante en unas cuantas iteraciones, sin adivinar.
Conceptos clave
- eval.json: el archivo que prueba la salida de la skill: define entradas concretas y revisa la calidad del output
- trigger_eval.json: prueba la activación: cuándo la skill debe dispararse y cuándo no
- Pass rate: el porcentaje de casos de prueba que la skill pasó con éxito
- Assertions: verificaciones concretas: cantidad exacta, límite de caracteres, formato correcto, pertinencia
- El ciclo de mejora: escribir → eval → encontrar las debilidades → mejorar → eval otra vez
- Skill Creator: el plugin
skill-creatordel catálogo oficial de Anthropic, que te ayuda a crear las pruebas y correrlas
Sobre los nombres de los archivos. El Skill Creator actual (a octubre de 2026, según la documentación de Claude Code) guarda las pruebas en evals/evals.json, registra las calificaciones de las verificaciones en grading.json y la comparación "con la skill y sin ella" en benchmark.json, y comprueba la activación ajustando la descripción (description tuning) con conjuntos de solicitudes que "deben / no deben activarla". Abajo los archivos se llaman eval.json y trigger_eval.json, como en el esquema didáctico: el principio es el mismo, y los nombres y campos exactos los ves en lo que el plugin cree en tu proyecto.
Teoría
Qué es un eval y para qué sirve
Sin eval, mejoras la skill por sensación: "parece que quedó mejor". Con eval, ves números.
Un ejemplo de una demostración didáctica (las cifras son ilustrativas; las tuyas serán otras): una skill que genera títulos para YouTube se probó con un eval:
| Métrica | Con la skill | Sin la skill |
|---|---|---|
| Pass rate | 100% | 33–50% |
| Cantidad exacta (10 títulos) | 6/6 pruebas | 2/6 pruebas |
| Límite de caracteres (60) | se cumple al 100% | se rompe seguido |
| Variedad de formulaciones | alta | baja |
Una iteración y la diferencia ya se ve. Sin eval, este análisis habría requerido muchas pruebas manuales.
eval.json: probar la calidad del output
Es un archivo con 3–5 casos de prueba. Cada caso tiene:
- Input: una solicitud concreta a la skill
- Expected: lo que debería salir
- Assertions: verificaciones concretas que se pueden medir
Estructura de eval.json:
{
"skill": "youtube-title-generation",
"test_cases": [
{
"id": "beginner-coding-video",
"input": {
"topic": "Claude Code para principiantes",
"angle": "primeros pasos sin saber programar",
"count": 10
},
"assertions": [
{
"type": "exact_count",
"value": 10,
"description": "Debe haber exactamente 10 títulos"
},
{
"type": "max_length",
"value": 60,
"description": "Cada título tiene como máximo 60 caracteres"
},
{
"type": "framework_adherence",
"description": "Se usan los marcos: curiosidad, especificidad, emoción"
},
{
"type": "topic_relevance",
"description": "Todos los títulos son pertinentes al tema Claude Code para principiantes"
},
{
"type": "variety",
"description": "Al menos 5 estructuras de título distintas (no la misma plantilla)"
}
]
},
{
"id": "tool-comparison-video",
"input": {
"topic": "Comparación VS Code vs Cursor vs Devin Desktop (antes Windsurf)",
"angle": "qué debe elegir un desarrollador en 2026",
"count": 10
},
"assertions": [
{"type": "exact_count", "value": 10},
{"type": "max_length", "value": 60},
{"type": "includes_comparison", "description": "Al menos 3 títulos tienen una comparación explícita"},
{"type": "framework_adherence"},
{"type": "variety"}
]
}
]
}trigger_eval.json: probar la activación
La skill debe dispararse con las solicitudes correctas y no dispararse con las ajenas. El trigger eval revisa justo eso.
Estructura: 20 pruebas, 10 "debe activarla" + 10 "no debe":
{
"skill": "youtube-title-generation",
"trigger_tests": {
"should_trigger": [
"inventa títulos para un video sobre IA",
"dame 10 ideas para el nombre de un video",
"ayúdame a ponerle nombre a un video sobre Claude Code",
"brainstorm YouTube titles for my tutorial",
"qué títulos harán que la gente le dé clic al video",
"quiero 15 opciones de título para comparar",
"genera títulos sobre mi tema",
"qué pongo en el nombre del video",
"suggestions for video title",
"inventa títulos que enganchen"
],
"should_not_trigger": [
"escribe un guion para un video de YouTube",
"haz una miniatura para el canal",
"cómo mejorar el SEO del canal",
"escribe un post de blog sobre este tema",
"cómo conseguir suscriptores en YouTube",
"ayúdame con la descripción del video",
"estrategia de crecimiento del canal",
"análisis de la competencia en el nicho",
"cómo editar video",
"arma un calendario de contenido para el mes"
]
}
}El ciclo de automejora
No es una prueba de una sola vez. Es un ciclo que repites hasta que quedas satisfecho.
Versión 1 de la skill
↓
Correr el eval → resultado: 60% de pass rate
↓
Análisis: ¿qué falló exactamente?
- exact_count: 8 de 10 (no cuenta bien)
- max_length: se rompe en 3 casos
↓
Mejorar la skill:
- agregar la regla explícita "siempre exactamente N títulos"
- agregar la regla "máximo 60 caracteres, revisa cada uno"
↓
Versión 2 de la skill
↓
Correr el eval → resultado: 90% de pass rate
↓
Una iteración más → 100%La idea del ciclo: dile a la skill que mejore, corre el eval otra vez y mira los números. Es un ciclo repetido en el que la skill mejora con datos y no con sensaciones (siempre que las mejoras las apruebes tú).
Errores comunes al trabajar con evals
No correr el eval después de cambiar la skill. Cambiaste una línea de la skill: corre el eval. Un cambio pequeño puede romper la activación o cambiar el formato del output. El eval lo mostrará rápido.
Muy pocos casos de prueba. 1-2 casos no cubren los casos límite. Mínimo 3 casos para eval.json y 10+10 para trigger_eval.json (10 "debe activarla" + 10 "no debe").
Probar solo el camino feliz. "La skill funciona cuando todo va bien" no basta. Agrega casos con entrada incorrecta, datos vacíos y valores límite.
No guardar los resultados del eval entre iteraciones. Si no anotas el pass rate de cada versión, no ves el avance. Lleva un registro: v1 = 44%, v2 = 71%, v3 = 89%.
Un eval.json real con 3 casos de prueba
{
"skill": "email-cold-outreach",
"test_cases": [
{
"id": "saas-founder",
"input": {
"recipient_role": "CEO de una startup SaaS",
"product": "automatización de soporte con IA",
"tone": "professional"
},
"assertions": [
{"type": "max_length", "value": 200, "description": "Máximo 200 palabras"},
{"type": "includes", "value": "call-to-action", "description": "Hay un CTA concreto"},
{"type": "excludes", "value": "palabras-spam", "description": "Sin palabras como: gratis, urgente, oferta única"}
]
},
{
"id": "ecommerce-manager",
"input": {
"recipient_role": "Especialista en marketing de e-commerce",
"product": "auditoría SEO",
"tone": "casual"
},
"assertions": [
{"type": "max_length", "value": 150, "description": "Casual = más corto"},
{"type": "tone_check", "description": "Tono informal, sin lenguaje burocrático"},
{"type": "includes", "value": "personalization", "description": "Está personalizado según el puesto"}
]
},
{
"id": "edge-case-empty",
"input": {
"recipient_role": "",
"product": "AI tool",
"tone": "professional"
},
"assertions": [
{"type": "graceful_handling", "description": "La skill maneja el campo vacío sin error"},
{"type": "fallback", "description": "Usa un saludo genérico si no se indica el puesto"}
]
}
]
}Cómo correr un eval: los comandos
Primero instala el plugin (el nombre del catálogo te lo muestra el menú /plugin):
/plugin install skill-creator@claude-plugins-official
Crear un eval para una skill existente y correrlo:
Revisa mi skill youtube-title-generation con skill-creator: arma las pruebas y córrelas
En la documentación de Claude Code, el ejemplo de formulación es: "evaluate my summarize-changes skill with skill-creator". Las pruebas quedan en la carpeta evals/ dentro de la carpeta de la skill, y cada corrida va en un subagente aparte.
Formato de la carpeta de la skill después de crear el eval (esquema para entenderlo; los nombres reales de los archivos pueden variar):
.claude/skills/youtube-title-generation/
├── SKILL.md ← archivo principal de la skill
├── evals/
│ ├── eval.json ← pruebas de calidad del output (en el plugin: evals.json)
│ └── trigger_eval.json ← pruebas de activación
└── references/
└── title-examples.md ← ejemplos de títulos (si los hay)Las métricas del reporte del eval
Después de correrlo, obtienes un reporte:
EVAL REPORT: youtube-title-generation ====================================== Test case 1: "Claude Code para principiantes" WITH skill: 6/6 assertions PASSED ✓ WITHOUT skill: 2/6 assertions passed ✗ Test case 2: "VS Code vs Cursor vs Devin Desktop" WITH skill: 5/6 assertions PASSED ✓ WITHOUT skill: 3/6 assertions passed ✗ SUMMARY: With skill: 91.7% pass rate (11/12 assertions) Without skill: 41.7% pass rate (5/12 assertions) ANALYSIS: Biggest advantage: format compliance (+100%) Weakness found: exact_count failed in test 2 Recommendation: add explicit counting rule to skill
Cuando ves "Weakness found", es una pista de qué mejorar exactamente en la skill. No adivinas. Los números hablan solos.
Práctica
Tarea: crear un eval para una skill existente
- Elige cualquier skill que hayas creado en lecciones anteriores (o crea una sencilla para este ejercicio)
- Da la instrucción:
Arma las pruebas para mi skill [nombre] con skill-creator; Skill Creator generará los casos de prueba y las verificaciones de activación - Revisa los eval.json y trigger_eval.json creados: ¿entiendes qué revisan?
- Da la instrucción:
Corre las pruebas de mi skill [nombre] - Lee el reporte: ¿qué pass rate tiene? ¿Qué falló?
- Mejora la skill a partir de las debilidades que encontró el eval
- Corre el eval otra vez y compara el pass rate de antes y después
Meta: llegar al menos a 80% de pass rate (una referencia aproximada) y entender la lógica de la iteración
Herramientas y recursos
- Skill Creator: se instala con
/plugin install skill-creator@claude-plugins-official(o búscalo en el menú/plugin) - eval.json (en el plugin,
evals/evals.json): pruebas de calidad; se crean en la carpetaevals/dentro de la skill - trigger_eval.json: pruebas de activación (en el plugin es el ajuste de la descripción con conjuntos de "debe / no debe activarla")
- Documentación de Skills en Claude Code: la guía oficial de skills, sección sobre cómo probarlas
- Claude Code: solicitudes como "revisa mi skill con skill-creator" funcionan en el chat
Conclusiones clave
El eval saca la mejora de las skills del terreno de las sensaciones y la lleva al de los números. El pass rate sube con iteraciones, no adivinando (en la demo, de 60% a más de 90% en un par de iteraciones; cifras ilustrativas).
eval.json prueba la calidad del output (lo que produce la skill). trigger_eval.json prueba cuándo debe activarse la skill. Hacen falta los dos.
El ciclo: skill → eval → encontrar la debilidad → mejorar → eval otra vez. Repítelo hasta que el resultado te convenza. No te quedes con la primera versión.
Lecciones relacionadas
- ← Creamos una skill desde cero EN VIVO: crear una skill con Skill Creator, primer contacto con los evals
- ← Arquitectura de skills: los dos arquetipos de skills, la auditoría trimestral
- ← Qué son las Skills: los conceptos básicos de las skills y el frontmatter
Siguiente lección
→ Use Don't Build: el ecosistema de skills: cuándo usar algo ya hecho y cuándo crear lo tuyo. Después, Hooks: reglas automáticas de Claude Code.
La marca se guarda solo en este navegador y no se envía a ningún sitio. Mi progreso