El skill de 10 horas supera siempre al de 10 minutos

Pensé que escribir un Skill consistía en soltar un archivo SKILL.md en una carpeta y pasar a otra cosa. Diez minutos, listo. Funcionó bien hasta que vi repetirse los mismos errores en cada invocación y me di cuenta de que no tenía forma de saber si el Skill hacía realmente lo que yo pretendía.

Entonces Thariq, uno de los ingenieros que construyen Claude Code en Anthropic, publicó algo que me reencuadró todo: «Usar Skills bien es una cuestión de habilidad».

Esa frase se me quedó grabada porque coincidía exactamente con lo que estaba viendo. La diferencia entre un archivo markdown rápido y una carpeta de Skill bien estructurada se notaba en la calidad real de los resultados, no solo en teoría.

Un Skill es una carpeta, no un archivo

El malentendido más habitual es que un Skill equivale a un único archivo SKILL.md. En la práctica, un Skill es una carpeta que contiene scripts, código de referencia, configuración y el archivo markdown que los cohesiona.

El enfoque interno de Anthropic utiliza lo que denominan divulgación progresiva. En lugar de meter todo en un único prompt, organizan los archivos de modo que Claude lea solo lo que necesita en el momento en que lo necesita. Un archivo references/api.md contiene las firmas de funciones que Claude carga bajo demanda. Un directorio assets/ incluye plantillas de salida para que el prompt no tenga que describir el formato. Los scripts de validación permiten que Claude compruebe su propio resultado antes de devolverlo.

Si abres el repositorio skill-creator, verás este principio en acción. Los directorios agents/, references/ y scripts/ conviven junto al SKILL.md. La herramienta que construye Skills está construida como uno de ellos.

Los Gotchas importan más que el cuerpo del prompt

Thariq calificó la sección de Gotchas como «el contenido de mayor señal» de un Skill. No las instrucciones principales, no los ejemplos. Los Gotchas.

Esto encaja con mi experiencia. Construí un Skill sin sección de Gotchas y cometí el mismo error tres veces seguidas. En el momento en que añadí una línea documentando ese patrón de fallo concreto, dejó de ocurrir.

El razonamiento es sencillo. Claude ya sabe la mayor parte de lo que escribirías en el cuerpo del prompt. Decirle cómo escribir TypeScript o formatear JSON es repetir cosas que maneja bien por defecto. Pero decirle qué no hacer en tu contexto específico es información genuinamente nueva.

Algunos principios del hilo de Thariq que me han resultado fiables: no indiques lo obvio, porque las instrucciones redundantes pueden degradar el rendimiento; evita encorsetar con pasos demasiado específicos, porque eso elimina la capacidad de Claude para adaptarse; y recuerda que el campo description no es documentación para personas, sino el input que Claude utiliza para decidir cuándo activar el Skill.

Skill Creator convierte «parece funcionar» en «verificado»

La actualización de Skill Creator de hace dos semanas cambió mi forma de entender la calidad de los Skills. Defines prompts de prueba, estableces los resultados esperados y la herramienta verifica si el Skill produce realmente los resultados correctos. Es testing unitario para prompts.

Añadí evaluaciones a un Skill que llevaba semanas usando. Dos casos de prueba que daba por superados fallaron de inmediato. Los ajustes eran pequeños, pero la calidad de los resultados mejoró de forma apreciable una vez aplicados.

Hay una distinción útil entre dos tipos de Skills. Los Skills de ampliación de capacidades enseñan a Claude algo que no hace bien por sí solo. Los Skills de preferencia codificada imponen el flujo de trabajo o los estándares específicos de un equipo. El primer tipo tiene una fecha de caducidad natural, porque las mejoras del modelo terminan por hacerlo innecesario. El segundo tipo conserva su valor mientras exista el flujo de trabajo. Las evaluaciones te ayudan a detectar el momento en que un Skill de ampliación de capacidades se convierte en peso muerto.

El tooling incluye un modo benchmark para hacer seguimiento de tasas de acierto y uso de tokens a lo largo de las actualizaciones del modelo, ejecución paralela multi-agente para evitar la contaminación de contexto durante las pruebas, y un agente comparador que realiza comparaciones A/B ciegas entre resultados con y sin el Skill aplicado.

El retorno compuesto

Entre los cientos de Skills que he visto y las decenas que mantengo, un patrón se repite sin excepción: el valor de un Skill viene de la iteración, no del borrador inicial.

La estructura de carpetas es como das forma a la ventana de contexto de Claude. Los Gotchas convierten tus fallos en conocimiento reutilizable. Las evaluaciones miden si ese conocimiento sigue siendo válido.

Escribir un SKILL.md lleva diez minutos. Añadir Gotchas de fallos reales, construir casos de evaluación e incluir scripts de validación se acerca a las diez horas. Esa inversión se recupera cada vez que el Skill se ejecuta. Monta uno esta noche. Por la mañana, habrá hecho trabajo que tú no habrás tenido que hacer.