🧪 Escribir 2-3 prompts de prueba realistas
Después del borrador, crea 2-3 test prompts realistas — el tipo de cosa que escribiría un usuario real. Muéstrale al usuario antes de ejecutarlo: "Aquí hay algunos casos de prueba que quiero probar. ¿Están bien o quieres agregar más?". Guarda los prompts en evals/evals.json todavía sin assertions; vienen después, mientras se ejecutan las runs.
✗ Prompt artificial
"Da formato a estos datos"
"Crea un gráfico"
Demasiado genérico. No prueba nada ni activa skills.
✓ Prompt realista
"ok, mi jefa me mandó un xlsx (está en Descargas, algo como 'Q4 sales final FINAL v2.xlsx') y quiere una columna de margen de ganancia en %. Ingresos en la columna C, costos en la D, creo"
Concreto, con historia de fondo, rutas y detalles reales.
evals/evals.json — solo prompts, todavía sin assertions:
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "User's task prompt",
"expected_output": "Description of expected result",
"files": []
}
]
}
⚖️ Ejecutar con skill vs. baseline en el mismo turno
Para cada caso de prueba, activa dos subagents en el mismo turno: una con la skill y otra sin ella (baseline). Esto importa: no ejecutes primero las que tienen skill y después vuelvas a las baselines. Lánzalas todas a la vez para que terminen más o menos al mismo tiempo.
Ejecución con skill
Apunta a la ruta de la skill. Guarda en iteration-N/eval-ID/with_skill/outputs/.
Baseline — skill nueva
El mismo prompt, sin ninguna skill. Guarda en without_skill/outputs/.
Baseline — skill existente
La versión anterior. Antes de editar, haz una snapshot (cp -r skill snapshot/) y señala el baseline para él. Guarda en old_skill/outputs/.
💡 ¿Por qué la línea base?
Sin comparar con el baseline, no sabes si la skill aportó algo. Quizá el modelo ya habría resuelto el caso por sí solo. El baseline es lo que distingue "la skill ayudó" de "esto habría pasado de todos modos".
📊 Evaluar: cualitativo + evals cuantitativos
La evaluación tiene dos frentes. Cualitativa: revisar los outputs en el viewer, hacer clic en cada caso y dejar comentarios. Cuantitativa: assertions verificables objetivamente que producen un pass_rate. Las skills subjetivas (estilo, diseño) se evalúan mejor solo de forma cualitativa: no fuerces assertions cuando hace falta el criterio humano.
✗ Assertion mala
- ✗Subjetiva: "el output se ve bonito"
- ✗Nombre opaco: "check_1", "assert_x"
- ✗Siempre pasa, con o sin skill (no discrimina)
- ✗Forzada en una skill de escritura creativa
✓ Buena assertion
- ✓Verificable: «la columna margen existe y es %»
- ✓Nombre descriptivo, legible en el viewer
- ✓Comprobada con un script, no a ojo
- ✓Distingue with_skill del baseline
eval_metadata.json — con assertions agregadas:
{
"eval_id": 0,
"eval_name": "margem-lucro-xlsx",
"prompt": "The user's task prompt",
"assertions": [
"Arquivo .xlsx de saída existe",
"Coluna 'margem' presente e formatada como %",
"Valores batem com (C - D) / C"
]
}
🎯 Muestra antes de juzgar
Genera el eval viewer con generate_review.py y pon los resultados delante de la persona antes de que tú mismo intentes corregirlo. La pestaña «Outputs» muestra un caso a la vez; la pestaña «Benchmark» muestra pass_rate, tiempo y tokens por configuración, con promedio ± desviación y el delta.
🧠 Cómo pensar la mejora
Este es el corazón del ciclo. La gran idea: la skill se usará un millón de veces en distintos prompts. Tú y el usuario iteran con unos pocos ejemplos porque es rápido, pero si la skill solo funciona con esos ejemplos, es inútil. Generaliza a partir de los comentarios en lugar de sobreajustar.
Cuatro formas de pensar
Generaliza a partir del feedback
Evita los cambios minuciosos para ajustar de más y los MUSTs opresivos. Si un problema persiste, prueba otras metáforas o patrones de trabajo: es barato probar y puede dar muy buenos resultados.
Manténlo conciso
Elimina lo que no esté aportando. Lee las transcripciones, no solo los resultados finales: si la skill hace que el modelo pierda tiempo, elimina la parte que lo causa y observa qué sucede.
Explica el porqué
Aunque los comentarios del usuario sean escuetos o frustrados, entiende la tarea y transmite esa comprensión. ALWAYS/NEVER en mayúsculas es una señal de alerta — reformúlalo explicando el motivo.
Fíjate en el trabajo repetido
Si los 3 casos de prueba escribieron un build_chart.py parecido, es una señal clara de que conviene agrupar este script. Escríbelo una vez, ponlo en scripts/, ahórrate cada invocación futura.
💡 El tiempo para pensar no es el cuello de botella
El consejo de skill-creator es literal: escribe una revisión en borrador, vuelve a mirarla con ojos nuevos y mejórala. Ponte en el lugar del usuario y entiende qué quiere y qué necesita de verdad. Vale la pena reflexionar.
🔁 El ciclo de iteración
Con la mejora en mente, ejecuta el ciclo: aplicar → volver a ejecutar → revisar → repetir. Cada iteración va en su propio directorio (iteration-2/, iteration-3/...), incluidos los baselines.
Aplica las mejoras
Edita el SKILL.md basándote en los comentarios y en lo que generalizaste a partir de ellos.
Vuelve a ejecutar todos los test cases
En una nueva iteration-N+1/, incluidos los baselines. Skill nueva → baseline siempre without_skill.
Revísalo con el usuario
Inicia el reviewer con --previous-workspace apuntando a la iteración anterior, para comparar.
Lee el feedback y repite
Feedback vacío = al usuario le pareció bien. Enfócate en los casos con quejas específicas.
Cuándo parar
- •El usuario dice que está feliz
- •Todo el feedback está vacío (todo bien)
- •No estás logrando avances significativos
🎚️ Optimización de description
La description es el mecanismo principal que decide si Claude invoca la skill. Después de crearla o mejorarla, optimízala para que se active con mayor precisión. Genera ~20 consultas de activación — una mezcla de should-trigger e should-not-trigger — y ejecuta el ciclo, eligiendo la description según la métrica del conjunto de pruebas.
✓ debería activarse (8-10)
- ✓La misma intención, formulaciones diferentes (formales/casuales)
- ✓Casos en los que el usuario no nombra la skill, pero la necesita
- ✓Usos poco comunes y conflictos con otra skill en los que esta debe prevalecer
✗ no debería activarse (8-10)
- →Near-misses: comparten palabras clave, pero necesitan otra cosa
- →Dominios adyacentes y frases ambiguas
- →Evita negativos obvios — «escribe un fibonacci» no prueba nada
trigger-eval.json — consultas con etiqueta:
[
{"query": "the user prompt", "should_trigger": true},
{"query": "near-miss tricky prompt", "should_trigger": false}
]
El ciclo automático
O run_loop.py divide el eval set en 60% train y 40% held-out test, evalúa la descripción actual (ejecutando cada query 3x para obtener un trigger rate confiable), llama a Claude para proponer mejoras según lo que falló y vuelve a evaluar — hasta 5 iteraciones. Usa el model ID que está ejecutando la sesión para que la prueba de activación coincida con lo que experimenta el usuario.
Al final, devuelve best_description — elegida por el test score, no por el train, para evitar el overfit. Aplícalo en el frontmatter y muestra el antes y el después.
💡 Cómo funciona la activación
Las skills aparecen en available_skills con name + description, y Claude decide consultarla según la description. Pero solo la consulta para tareas que no puede resolver fácilmente por sí solo — "lee este PDF" puede no activarla aunque la description sea perfecta. Por eso, las queries de prueba deben ser lo bastante sustantivas para que Claude pueda beneficiarse de la skill.
✅ Resumen del módulo
Próximo:
Módulo 4.3 — ⭐ Las mejores meta-skills (para crear skills) — skill-creator, find-skills y scaffolding: las herramientas de quienes crean skills y dónde encaja cada una en el flujo.