Cómo probar una skill de Claude: evals, disparo y optimización de la descripción

Una skill que nunca se dispara no es una skill. Es un archivo.

Escribir una skill de Claude es la parte fácil. Saber si funciona de verdad (si se dispara cuando la necesitas y se queda quieta cuando no debe) requiere evals.

Si todavía no pusiste una skill en uso, empieza por la guía completa para construir skills en Claude Code. Para dejar bien la estructura de SKILL.md antes de probar, lee la guía de estructura y frontmatter de SKILL.md. Para ejemplos reales de skills probadas, mira los ejemplos de skills de Claude.

Las skills tienden a dispararse de menos, y no lo notas

La falla más común es el undertrigger: la skill existe, la descripción se ve bien y Claude nunca la carga. Escribes una query. No pasa nada. Asumes que funcionó. No funcionó.

Claude solo recurre a una skill cuando decide que la tarea no se resuelve trivialmente con sus propios pesos. Una descripción vaga o pasiva (“esta skill ayuda con X”) se lee como opcional. Claude la salta. La descripción es la única señal que Claude revisa antes de decidir si carga una skill. Si no obliga a actuar, no se carga nada, y nunca te enteras: el modelo responde con seguridad a partir de sus datos de entrenamiento y sigue adelante.

Arma el set de evals antes de tocar la descripción

Arma unas 20 queries de eval antes de ajustar nada. La mitad deben ser casos en los que la skill debe dispararse: queries reales de los casos de uso previstos. La otra mitad deben ser queries en las que no debe dispararse: temas vecinos, intención superpuesta, cosas que un usuario razonable podría preguntar y que la skill nunca se diseñó para manejar.

Divídelas 60/40: doce para train (el set contra el que iteras) y ocho apartadas para test. Esa división importa. Si optimizas solo contra tus queries de train, vas a hacer overfitting. La descripción se vuelve sospechosamente buena en esos doce ejemplos exactos y falla en cualquier cosa un poco distinta. El set de test es la única medida honesta.

Corre cada query tres veces antes de registrar el puntaje. La decisión de disparo de Claude es probabilística. Una sola ejecución puede darte un falso positivo o un falso negativo. Tres ejecuciones por query te dan una tasa confiable: 0/3, 1/3, 2/3, 3/3. La meta es una tasa de disparo por encima del 80% en las queries que deben dispararse y por debajo del 20% en las que no. Todo lo que quede fuera de esa franja vale la pena corregir.

El loop de evals

El presupuesto es de cinco rondas. Más que eso y normalmente estás persiguiendo ruido en tu set de train en lugar de mejorar la skill. En cada ronda: propón un cambio en la descripción, vuelve a correr las queries de train tres veces cada una, registra la tasa de disparo. Después de cinco rondas, elige la descripción con el mejor puntaje en el set de test, no en el de train. Esa es la que va a producción.

Loop de eval de la descripción

Entrada

~20 queries: mezcla de debe-dispararse y no-debe-dispararse, divididas 60/40 en train/test

↓

1. 01Corre el baseline

   Lanza cada query de train 3× contra la descripción actual. Registra la tasa de disparo de los grupos debe-dispararse y no-debe-dispararse por separado.

   ↓
2. 02Diagnostica la brecha

   ¿Undertrigger? Agrega frases de disparo explícitas y haz la descripción un poco insistente. ¿Over-trigger? Acota el alcance y agrega contexto de cuándo no usarla.

   ↓
3. 03Propón un cambio

   Una edición por ronda. Cambiar varias cosas a la vez hace imposible saber qué movió la aguja.

   ↓
4. 04Vuelve a correr el set de train

   Vuelve a correr todas las queries de train, 3× cada una. Registra la nueva tasa de disparo. Guarda cada versión. Quizás quieras volver atrás.

   ↓
5. 05Repite hasta 5 rondas y elige por el puntaje de test

   Después de 5 rondas (o cuando la tasa de train se estanque), para. Evalúa cada descripción candidata en el set de test apartado. La que tenga mejor puntaje de test va a producción.

↓

Salida

Una descripción que se dispara de forma confiable con queries reales: verificado, no supuesto

La regla de un cambio por ronda es la disciplina que vuelve útil la iteración. Si cambias la descripción, agregas una frase de disparo y renombras la skill en la misma pasada, no puedes atribuir el cambio en la tasa de disparo a ninguna decisión en particular. Trata la descripción como la variable y deja todo lo demás fijo.

Tres modos de falla, cada uno con un arreglo distinto

Después de correr este loop en una docena de skills en producción, los mismos tres patrones de falla siguen apareciendo. Viven en partes distintas de la skill y necesitan arreglos completamente distintos. Confundirlos desperdicia rondas.

Modos de falla de disparo y de salida

Undertrigger y over-trigger son problemas de descripción. El drift de salida es un problema de referencias. Cada uno necesita una palanca distinta.

Modo de falla	Síntoma	Arreglo
Undertrigger	La skill existe, pero rara vez se dispara con queries relevantes	Agrega verbos de disparo explícitos; reescribe la descripción para que sea un poco insistente
Over-trigger	Se dispara con queries vecinas para las que la skill no fue diseñada	Acota el alcance; agrega ejemplos de cuándo NO usarla en la descripción
Drift de salida	Se dispara bien, pero ignora tus referencias; responde con sus pesos	Agrega contraejemplos y antipatrones a los archivos de referencia; refuerza el mapa de carga

Undertrigger y over-trigger son ambos problemas de descripción. Corre el loop de evals de arriba. El drift de salida es un problema de referencias. La skill se disparó. El modelo simplemente eligió no usar lo que construiste. Eso se arregla en los archivos de referencia y en el mapa de carga, no en la descripción.

Calidad de la salida: la prueba que todos se saltan

La tasa de disparo solo te dice si la skill se disparó. No dice nada sobre si la respuesta fue buena. Esa es otra prueba, y la mayoría nunca la corre.

La prueba es simple: dale a Claude la misma entrada real dos veces. Una con la skill activa, otra sin ella. Compara las dos respuestas con cinco criterios.

Checklist de calidad de la salida

• ✓Obligatorio:
  Cargó el archivo de referencia correcto.La respuesta debe citar o aplicar el framework o los criterios de decisión específicos de tus referencias, no un consejo genérico que Claude podría dar sin ellas.
• ✓Obligatorio:
  Aplicó el framework, no solo la voz.Que el tono y el vocabulario coincidan con la skill es necesario, pero no suficiente. El framework (la Value Equation, el modelo RAISE, tu checklist de decisión) debe estructurar la respuesta, no solo darle sabor.
• ✓Obligatorio:
  Dejó de lado el "depende" genérico.Sin la skill, Claude da respuestas tibias. Con ella, deberías ver juicios concretos. Si la respuesta todavía suena a 'depende' sin ninguna decisión, la skill no está anclando la salida.
• ✓Obligatorio:
  Es consistente en dos sesiones separadas.Corre la misma entrada en una sesión nueva. La skill debe anclar el mismo método las dos veces. Una variación grande entre sesiones significa que las referencias son demasiado escasas o que el mapa de carga es ambiguo.
• ✓Obligatorio:
  La respuesta fallaría sin la skill.Esa es la vara real. Si Claude produce una respuesta así de buena solo con sus pesos, la skill no está aportando valor. La diferencia entre con skill y sin skill debe ser obvia.

Esta prueba toma diez minutos, y la mayoría se la salta porque exige correr la misma query dos veces y comparar con cuidado. Es la única forma de saber si tus referencias destiladas realmente llegan a la respuesta o están en un directorio sin que nadie las lea mientras Claude improvisa con sus datos de entrenamiento.

Iterar la descripción: tres movimientos concretos

Después de correr el eval de tasa de disparo, la mayoría de las descripciones necesita un cambio estructural: son demasiado pasivas.

Compara estas dos descripciones para la misma skill:

Antes: “Esta skill ayuda con la evaluación de ofertas usando los frameworks de Hormozi.”

Después: “Usa esta skill siempre que alguien te pida evaluar, criticar, mejorar o ponerle precio a una oferta, un value stack o una garantía. Antes de responder, carga references/01-value-equation.md y references/11-decision-checklist.md.”

La primera descripción le dice a Claude qué es la skill. La segunda le dice cuándo usarla y qué hacer primero. Esa diferencia suele llevar la tasa de disparo del 40% a más del 90% en un set de evals real.

Tres movimientos que arreglan el undertrigger.

Nombra los verbos de disparo explícitamente. Enuméralos: “evaluar, criticar, revisar, mejorar, auditar, diagnosticar”. Si el verbo del usuario aparece en la descripción, Claude puede hacer el match directo. No lo obligues a adivinar que “échale un ojo a mi oferta” significa evaluar.

Agrega una oración de cuándo usarla. “Usa esta skill siempre que…” es una instrucción, no una etiqueta. El condicional lo vuelve explícito.

Nombra la primera referencia que debe cargar. Hacer obligatoria la carga de la referencia en la descripción la convierte de opción en compuerta. El modelo no puede responder de forma genérica si la descripción ya le dijo qué archivo abrir primero.

Para skills que se disparan de más, aplica lo inverso. Agrega una oración de cuándo NO usarla: “No uses esta skill para escritura general, code review ni debugging técnico.” Ese límite se va a sostener.

Cuándo está lista la descripción

Una descripción está lista cuando la tasa de disparo en el set de test supera el 80/20, el checklist de calidad de la salida pasa con dos entradas reales y dos sesiones separadas producen respuestas consistentes para la misma query. Versiónala. Haz commit de la descripción en el directorio de la skill con una nota de qué cambió y por qué. Las skills se degradan: sale una versión nueva de Claude, cambian los patrones de uso y la tasa de disparo cae. Vas a querer ese historial cuando tengas que depurarlo dentro de seis meses.

Para ver cómo es por dentro un SKILL.md listo para producción, la guía de estructura y frontmatter de SKILL.md cubre los campos que afectan el disparo y la carga. Para ejemplos concretos de skills que pasaron por este proceso, mira los ejemplos de skills de Claude.

Los evals cierran la distancia entre publicada y confiable

Construir una skill lleva una tarde. Saber que funciona es otra cosa. No aparece en la cantidad de archivos, pero aparece en si la skill realmente se usa.

Veinte queries de eval. Una división 60/40 en train/test. Tres ejecuciones por query. Hasta cinco rondas de edición de la descripción. Elige la ganadora por el puntaje en el set de test. Después corre el checklist de calidad de la salida para confirmar que tus referencias llegan a la respuesta, y no solo están guardadas en un directorio.

Ese es el protocolo completo. Nada glamoroso, pero es la diferencia entre una skill que desplegaste y una skill en la que confías.

Si todavía no escribiste tu primera skill, la guía para construir skills en Claude Code es el punto de partida correcto.

¿Cómo sé si mi skill realmente se está disparando?+

Corre la misma query tres veces y revisa si la respuesta aplica el framework de tu skill. Si la respuesta es genérica (ningún framework específico, ninguna señal de una referencia cargada, ninguna diferencia relevante con lo que Claude produciría sin la skill), probablemente no se disparó.

La prueba más limpia es la comparación con/sin: corre la query una vez con la skill presente y otra con el SKILL.md quitado temporalmente. Si las respuestas son idénticas, el disparo no es tu problema. La calidad de la salida sí.

¿Por qué correr cada query de eval tres veces en lugar de una?+

La decisión de disparo de Claude es probabilística. Una sola ejecución puede darte un falso positivo (la skill se dispara con una query con la que normalmente no lo haría) o un falso negativo (se la salta con una query que debería atrapar). Tres ejecuciones por query te dan una tasa: 0/3, 1/3, 2/3, 3/3. Lo bastante estable para tomar una decisión.

¿Por qué elegir la mejor descripción por el set de test y no por el de train?+

Porque puedes sobreajustar una descripción a tus queries de train. Después de cinco rondas de iteración, una descripción puede volverse muy buena justo en los doce ejemplos que probaste y fallar en cualquier cosa un poco distinta.

El set de test (las ocho queries que apartaste y contra las que nunca iteraste) es la única medida honesta de generalización. Si lo miras antes de dejar de iterar, deja de ser un test.

¿Cuál es la diferencia entre undertrigger y drift de salida?+

Undertrigger significa que la skill no se dispara. Drift de salida significa que se dispara, pero la respuesta igual ignora tus referencias y sale de los pesos de entrenamiento del modelo.

Los dos producen respuestas mediocres, pero los arreglos son completamente distintos. El undertrigger es un problema de descripción: itera el loop de evals. El drift de salida es un problema de referencias y de mapa de carga. La descripción ya está haciendo su trabajo.

¿De verdad necesito 20 queries de eval, o puedo usar menos?+

Para una skill acotada y bien definida (una que maneja un solo tipo de documento o una decisión específica), 15 suelen alcanzar. Con menos, la señal es demasiado ruidosa para iterar con confianza.

La división 60/40 importa más que el número absoluto. Necesitas suficientes ejemplos de train para iterar y suficientes ejemplos apartados para evaluar con justicia. No los juntes en un solo set.

¿Una descripción mejor siempre arregla una skill que no funciona?+

No. La descripción controla el disparo. Si la skill se dispara pero la salida sigue siendo genérica, el problema está en las referencias o en el mapa de carga, no en la descripción.

Corre siempre el checklist de calidad de la salida antes de gastar rondas de eval en editar la descripción. Si la respuesta con skill ya es claramente distinta de la respuesta sin skill, tu mecanismo de disparo está bien y estás resolviendo el problema equivocado.