Cómo probamos las Claude Skills: el protocolo SkillProof

Todo el sitio empezó con una skill que no hacía nada. A finales de 2025, una skill de productividad se estaba haciendo popular en X con varios miles de estrellas detrás. La instalamos, reiniciamos Claude Code, escribimos el caso de uso exacto del README, y vimos a Claude responder como si la skill no existiera. Revisamos el directorio: archivos presentes, frontmatter válido. Escribimos otra formulación. Nada. La skill nunca se activó ni una vez en cuarenta minutos, y nada en la página del repo lo habría predicho. Las estrellas miden si un README es emocionante. No dicen nada sobre si la carpeta de debajo funciona.

Esa noche nos dejó una pregunta que no pudimos sacudirnos: si una skill con tanta atención puede estar muerta al llegar, ¿cómo es el resto del ecosistema? Así que empezamos a instalar skills en una máquina limpia y a anotar lo que pasaba. La respuesta, documentada en nuestros datos de fallos, es que alrededor de la mitad de las skills comunitarias fallan antes de ayudar a nadie. Este artículo es la otra cara de ese hallazgo: el protocolo exacto detrás de cada veredicto en SkillProof, con suficiente detalle para que lo apliques a tu propia skill antes de publicarla.

El protocolo, paso a paso

Una prueba completa tarda entre 45 minutos y varios días, según la categoría. Una skill de documentos se demuestra en una sola sesión; una skill de revisión semanal tiene que sobrevivir a una semana real. En cualquier caso los pasos son los mismos, y el orden importa, porque cada uno condiciona al siguiente. No tiene sentido puntuar el resultado de una skill que nunca se activa.

Paso 0: un entorno limpio

Cada prueba empieza en un perfil de máquina con un directorio de skills vacío y ajustes por defecto de Claude Code. Esto suena a ceremonia hasta la primera vez que te salva. Las skills interactúan: una puede parecer que funciona porque otra skill en la máquina está haciendo el trabajo pesado en silencio. Aprendimos esto probando una skill de propuestas en una máquina que ya tenía instalada la skill docx. El resultado se veía genial. En un perfil limpio, la mitad del valor desaparecía, porque la skill de documentos había estado produciendo el .docx pulido todo el tiempo.

Paso 1: instalar desde las propias instrucciones del autor

Abrimos el README del repo y lo seguimos literalmente. No "averiguamos cómo instalarlo". Hacemos exactamente lo que escribió el autor, erratas incluidas, porque eso es lo que hará cualquier usuario real. Si los comandos realmente producen ~/.claude/skills/nombre/nombre/SKILL.md, un directorio de más, eso es una instalación fallida, aunque cualquiera que conozca el formato pudiera arreglarlo en diez segundos. Nosotros también podríamos arreglarlo. El punto es que el recién llegado que sigue las instrucciones a las 11 de la noche no puede, y concluirá que las skills de Claude están rotas en vez de que una ruta estaba mal.

Cualquier cosa que el README no mencione cuenta en su contra: dependencias no declaradas, instrucciones escritas para una versión de Claude Code de dos lanzamientos atrás. Anotamos el tiempo desde el clon hasta tener una skill funcionando, y si tuvimos que salir del README para lograrlo.

Paso 2: la batería de activación

Una skill instalada que nunca se activa es decoración. Así que antes de cualquier tarea real ejecutamos una batería de cinco prompts: tres formulaciones que deberían activarla, dos que no deberían.

Los tres prompts positivos son deliberadamente variados. Para una skill de documentos Word: "convierte estas notas en un informe que pueda enviar como .docx", luego "redacta este contrato como un archivo Word", y luego algo más indirecto como "necesito esto formateado correctamente para revisión legal". El primero es el propio ejemplo del README. El segundo usa vocabulario distinto para la misma intención. El tercero nunca nombra el formato de archivo, lo cual prueba si la descripción cubre el trabajo en vez de las palabras clave.

Los dos prompts negativos exploran la sobreactivación, el fallo del que nadie habla. Una skill de documentos que se activa cuando preguntas "resume este documento" (texto pegado, sin ningún archivo de por medio) está inyectando instrucciones en conversaciones donde no pertenecen, y eso lo pagas en contexto y en resultados raros. Una skill que se activa con todo es peor que una que no se activa con nada; al menos la muerta es fácil de diagnosticar.

Cinco de cinco es un resultado limpio. Por debajo de eso, anotamos qué formulaciones fallaron; el patrón suele ser diagnóstico. Una skill que solo se activa con la redacción exacta del README tiene una descripción escrita como eslogan en vez de como especificación de activación.

Paso 3: la prueba de referencia

Este es el corazón de la prueba y la razón por la que existe el protocolo. Tomamos una tarea real del dominio de la skill y la ejecutamos dos veces: una con la skill instalada, otra en el modelo desnudo con el mismo prompt exacto. Luego comparamos.

La comparación es la única pregunta que importa: ¿el resultado con la skill es claramente mejor que lo que Claude produce de todos modos? Claude ya es bueno en muchas cosas. Una skill de "mejora de escritura" que compite contra un modelo que ya escribe bien tiene que demostrar una diferencia, y la mayoría no puede. Cuando probamos frontend-design, ejecutamos el mismo brief de landing page de las dos maneras. La versión con la skill tenía una escala tipográfica real y una paleta intencional; la base tenía el aspecto de gradiente neón que todo el mundo reconoce. Esa diferencia se ganó un 10. Cuando los dos resultados son difíciles de distinguir, la skill no tiene razón de existir, por más agradable que sea su README.

Las entradas reales importan tanto como la comparación. Una hoja de cálculo con encabezados malformados, una carpeta de facturas donde un tercio de los archivos son escaneos. El rendimiento con datos de demostración es marketing; probamos la versión de un martes por la tarde del trabajo, porque esa es la versión que le vas a dar.

Paso 4: la contraverificación de la documentación

Por último, leemos todo el SKILL.md y todo lo que referencia, y comparamos las afirmaciones con lo que observamos. ¿Promete el README capacidades que la skill no tiene? ¿Divulga sus dependencias? ¿Hay algo enterrado a mitad del archivo que se parece menos a guía de tarea y más a inyección de prompt, o a una llamada de red que la documentación nunca menciona?

Este paso marca quizás una skill de cada diez, pero las que atrapa son las que más importan. Una skill es texto inyectado en el contexto de tu modelo. Leer cada línea antes de confiar es el mínimo, y tratamos esa lectura como parte del producto.

Las cuatro puntuaciones, y por qué el resultado cuenta doble

Cada skill probada recibe cuatro números, descritos en nuestra página de metodología. La versión corta, con lo que separa a un 5 de un 2:

Instala limpiamente (sobre 5). Un 5 significa que un recién llegado que sigue el README obtiene una skill funcionando en una instalación nueva sin desvíos. Un 2 significa que al final la hicimos funcionar con conocimiento que el README no contiene: arreglando rutas, leyendo el código fuente. La skill puede ser excelente; la puerta hacia ella está rota.

Se activa de forma fiable (sobre 5). Un 5 es cinco de cinco en la batería: las tres formulaciones positivas se activan, las dos negativas se quedan calladas. Un 2 se activa solo con la redacción tomada de su propio README, o se activa con trabajo que no tiene relación, o ambas cosas. Causa común en cualquiera de las dos direcciones: un campo de descripción escrito para impresionar a humanos en vez de para informar al modelo.

Resultado vs. base (sobre 10). Un 9 o un 10 significa que el resultado con la skill es inequívocamente mejor en una tarea real, el tipo de diferencia que notarías sin una tabla de puntuación. Un 4 significa que tuvimos que forzar la vista. Un 2 significa que la ejecución base fue igual de buena o mejor, lo cual pasa más de lo que a los autores les gustaría creer.

Documentación y honestidad (sobre 5). Un 5 significa que el README coincide con la realidad: afirmaciones precisas, dependencias declaradas, nada oculto. Un 2 significa promesas que la skill no puede cumplir o comportamiento que la documentación nunca menciona.

El resultado se puntúa sobre 10 mientras todo lo demás es sobre 5, y esa ponderación es deliberada: la calidad del resultado vale tanto como el resto de criterios juntos. Los problemas de instalación tienen soluciones alternativas. Los problemas de activación se pueden parchear editando un campo de descripción. Pero una skill cuyo resultado no supera la base no tiene arreglo de ninguna manera que importe. Las demás puntuaciones miden si puedes llegar al valor. La puntuación de resultado mide si hay algún valor.

Dos pruebas del registro: un 24 y un 17

Los números significan más con las pruebas adjuntas. Aquí va una de cada extremo del rango publicado.

Systematic-debugging, de la colección Superpowers de Jesse Vincent, obtuvo 24 de 25: instalación 5, activación 5, resultado 9, documentación 5. La instalación son dos comandos de plugin que funcionaron exactamente como estaban escritos, y la batería de activación salió cinco de cinco. La prueba de referencia es la parte que todavía sacamos en conversación: le dimos una condición de carrera que el Claude base ya había "arreglado" tres veces, cada arreglo una suposición que movía el síntoma de sitio. Con la skill cargada, Claude dejó de adivinar. Formó una hipótesis, escribió una prueba para comprobarla, vio la prueba fallar, y recorrió ese ciclo hasta encontrar la causa raíz real. La documentación promete un proceso de depuración disciplinado y eso es precisamente lo que vimos ocurrir. Ha sido un fijo de nuestra página de código desde entonces.

Proposal-builder, una skill comunitaria, obtuvo 17: instalación 3, activación 4, resultado 7, documentación 3. La primera ejecución fue un fallo en el sentido llano. Recién sacada de la caja, en un perfil limpio, no pudo entregar lo que su README promete: el resultado .docx pulido depende en silencio de tener instalada la skill docx, y el formato de marca depende de una plantilla de propuesta que el README apenas menciona. Sigue las instrucciones literalmente, como haría un usuario nuevo, y obtienes una pared de markdown donde debería haber una propuesta. Una vez instalamos la skill complementaria y configuramos una plantilla, ensambló una propuesta de marca genuinamente útil a partir de notas de llamada y precios. La capacidad es real. El camino hacia ella no está en el README, y las puntuaciones lo dicen exactamente así, hasta los pasos que faltan detallados en las notas de la prueba.

Esa brecha es la que el contador de estrellas no puede ver. Ambos repos parecen competentes desde fuera. Uno funciona en el momento en que sigues sus propias instrucciones. El otro funciona solo si ya sabes lo que se le olvidó contarte.

Qué significa un veredicto

Las puntuaciones se agrupan en uno de tres veredictos. El del medio confunde a la gente, así que seamos precisos.

Aprobado significa que la skill se instaló siguiendo las propias instrucciones del autor, se activó correctamente, y superó la base sin skill en una tarea real. De las 73 skills del catálogo, 35 llevan este veredicto.

Funciona con configuración significa que la skill entrega valor real, pero no recién sacada de la caja. Necesita primero una skill complementaria o un paso de configuración, y la ficha dice cuál. Diez skills están en esta categoría, y el veredicto no es un eufemismo de fallo. Algunas skills requieren configuración por diseño: una skill de directrices de marca se supone que es inútil hasta que rellenas tu paleta y voz, y una skill de revisión de pipeline no puede revisar un pipeline que no puede ver. El veredicto existe para que sepas qué te compra una hora honesta de configuración antes de gastarla.

En cola de pruebas significa que listamos la skill porque parece prometedora y todavía no hemos terminado de probarla. No se implica ningún veredicto en ninguna dirección; 28 skills están esperando. Las skills que fallan la prueba directamente tampoco reciben un borrado silencioso: las notas de la prueba dicen qué ejecutamos y qué se rompió, porque un fallo documentado te es más útil que un hueco en el catálogo.

Volver a probar, porque Claude sigue cambiando

Un veredicto es una instantánea, y el terreno debajo se mueve. Las skills se apoyan sobre un modelo, y los modelos se actualizan. Una descripción que se activaba de forma fiable en un lanzamiento de Claude Code puede empezar a fallar en el siguiente, porque la activación depende de cómo el modelo lee las descripciones, y esa lectura cambia. La deriva no es hipotética; hemos visto a una skill fiable empezar a ignorar una de sus tres formulaciones positivas tras un lanzamiento, sin que se cambiara un solo carácter de la skill.

Así que cada ficha lleva una fecha de prueba y la versión de Claude Code, y los lanzamientos importantes ponen toda la lista de aprobadas de vuelta en la cola de repruebas, empezando por las skills más instaladas. Cuando un veredicto cambia, la ficha cambia. Una fecha de prueba envejecida es tu señal para ponderar el veredicto en consecuencia; es el coste honesto de probar contra una plataforma en movimiento.

Lo que no probamos, y dónde el método es débil

Un protocolo que no se puede criticar es un protocolo que nadie describió con honestidad. Los límites conocidos:

Las tareas de muestra no pueden cubrir cada uso. Ejecutamos una o dos tareas reales por skill, elegidas para ser representativas, y una skill que brilla en nuestra hoja de cálculo de 40.000 filas puede tropezar igualmente en la tuya de 400.000. El veredicto es evidencia, nunca una garantía.

La puntuación de documentación se apoya en el criterio de un solo evaluador. Leer un SKILL.md buscando honestidad se parece más a editar que a medir, y dos lectores cuidadosos pueden ponderar la misma frase vaga de forma distinta. Publicamos las notas de la prueba en parte para que puedas auditarnos.

No probamos a escala ni en horizontes largos. Una máquina limpia, días en vez de meses. La degradación lenta y los flujos de trabajo que involucran varias skills a la vez quedan fuera del alcance del método por ahora.

La revisión de seguridad es una lectura, no una auditoría. Comprobamos llamadas de red no divulgadas e instrucciones con forma de inyección, pero un atacante decidido podría colar algo más allá de una lectura manual. Trata nuestra puntuación de documentación como un filtro, y mantén la guardia alta con cualquier cosa que toque credenciales.

Y la propia base se mueve. "Supera al Claude desnudo" significa el Claude desnudo en la fecha de la prueba; a medida que el modelo base mejora, algunas skills aprobadas verán su diferencia encogerse hacia cero. Una razón más por la que volver a probar no es opcional.

Ejecutar el protocolo en tu propia skill

Si estás a punto de publicar una skill, una versión condensada de esto tarda alrededor de una hora y te pone por delante de la mitad del ecosistema.

1. Perfil limpio. Directorio de skills vacío, ajustes por defecto. Tu máquina diaria esconde tus errores.
2. Instala solo desde tu README. Mejor todavía: dale el README a alguien que nunca haya visto el repo y observa. Cada pregunta que haga es una frase que falta.
3. Ejecuta la batería de cinco prompts. Tres formulaciones que deberían activarla, incluida una que nunca use tus palabras clave, más dos prompts adyacentes que no deberían. Arregla los fallos reescribiendo el campo de descripción, no añadiendo advertencias al README.
4. Haz la comparación de referencia. Misma tarea, con y sin tu skill. Si no puedes distinguir los resultados, reconsidera para qué sirve la skill antes de publicarla.
5. Vuelve a leer tu SKILL.md como escéptico. Cada afirmación que no puedas demostrar, córtala. Cada dependencia, declárala.
6. Verifica el formato con un linter. Los errores de frontmatter son la clase de fallo más prevenible que vemos, y un validador los detecta en segundos.

Preguntas frecuentes

¿Cuánto se tarda en probar una skill de Claude?

La autoprueba condensada tarda alrededor de una hora. Nuestro protocolo completo corre 45 minutos para una skill de documentos sencilla y hasta una semana para skills cuyo valor solo se ve con el tiempo, como las skills de revisión semanal. La batería de activación tarda minutos; la comparación de referencia es donde se van las horas.

¿Puedo probar una skill sin una segunda máquina?

Sí. Necesitas un perfil limpio, no hardware limpio. Apunta Claude Code a un directorio de skills vacío (o mueve el tuyo a un lado) y obtienes el aislamiento que importa: ninguna otra skill compitiendo por activaciones, ninguna cubriendo en silencio a la que estás probando.

¿Cuál es la razón más común por la que las skills fallan la prueba?

Un resultado que no supera la base, en alrededor del 35% de los fallos, con instalaciones rotas cerca detrás en el 30%. Los fallos de instalación duelen más porque son los más baratos de prevenir: el autor nunca siguió su propio README en una máquina que no era la suya.

¿Cómo consigo que prueben y listen mi skill en SkillProof?

Envíala aquí con el enlace al repo. Entra en la cola de descubrimiento, se prioriza por tracción y encaje de categoría, y luego pasa por el protocolo de esta página. Ejecuta primero la autoprueba y tus probabilidades de un veredicto aprobado suben, porque atraparás los mismos defectos que atraparíamos nosotros.

El protocolo no tiene nada de ingenioso. Es una máquina limpia, un README tomado en su palabra, cinco prompts, una comparación honesta. Lo que lo hace funcionar es que nadie más en la cadena hace ni siquiera eso: los autores prueban en sus propias máquinas, y las estrellas miden entusiasmo. La brecha entre esas dos cosas es donde vivía aquella skill de productividad muerta de finales de 2025. Seguimos cerrándola, una instalación a la vez.