El Skill de 10 Horas Supera al de 10 Minutos Siempre

Pensé que escribir un Skill significaba soltar un archivo SKILL.md en una carpeta y listo. Diez minutos y ya. Eso funcionó bien hasta que vi los mismos errores repetirse en cada invocación y me di cuenta de que no tenía forma de saber si el Skill realmente hacía lo que yo esperaba.

Entonces Thariq, uno de los ingenieros que construye Claude Code en Anthropic, publicó algo que 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 brecha entre un archivo markdown hecho a las corridas y una carpeta de Skill bien estructurada se notaba en la calidad real del output, no solo en la teoría.

Un Skill es una carpeta, no un archivo

El error más común es creer que un Skill equivale a un solo 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 une.

El enfoque interno de Anthropic usa lo que llaman divulgación progresiva. En lugar de meter todo en un solo prompt, organizan los archivos para que Claude lea únicamente lo que necesita en el momento en que lo necesita. Un archivo references/api.md guarda las firmas de funciones que Claude consulta bajo demanda. Un directorio assets/ contiene plantillas de output para que el prompt nunca tenga que describir el formato. Scripts de validación permiten que Claude verifique su propio output antes de devolverlo.

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

Los Gotchas importan más que el cuerpo del prompt

Thariq llamó a la sección de Gotchas el “contenido de mayor señal” en un Skill. No las instrucciones principales, no los ejemplos. Los Gotchas.

Eso coincide con mi experiencia. Armé un Skill sin sección de Gotchas y cometí el mismo error tres veces seguidas. En el momento en que agregué una línea documentando ese patrón de fallo específico, dejó de ocurrir.

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

Algunos principios del post de Thariq que me resultaron confiables: no decir lo obvio porque las instrucciones redundantes pueden degradar el rendimiento; evitar encorsetar con pasos demasiado específicos porque mata la capacidad de adaptación de Claude; y recordar que el campo description no es documentación para humanos, es el input que Claude usa para decidir cuándo activar el Skill.

Skill Creator convierte “parece que funciona” en “verificado”

La actualización de Skill Creator de hace dos semanas cambió cómo pienso en la calidad de los Skills. Uno define prompts de prueba, establece resultados esperados, y la herramienta verifica si el Skill realmente produce los resultados correctos. Es testing unitario para prompts.

Agregué evals a un Skill que venía usando desde hacía semanas. Dos casos de prueba que asumía que pasarían fallaron de inmediato. Los arreglos fueron pequeños, pero la calidad del output mejoró notablemente una vez aplicados.

Hay una distinción útil entre dos tipos de Skills. Los Skills de uplift de capacidad le enseñan a Claude algo que no puede hacer bien por sí solo. Los Skills de preferencia codificada imponen el flujo de trabajo o los estándares específicos de un equipo. El primero tiene una fecha de vencimiento natural porque las mejoras del modelo eventualmente lo hacen innecesario. El segundo sigue siendo valioso mientras exista el flujo de trabajo. Los evals ayudan a detectar el momento en que un Skill de uplift de capacidad se convierte en peso muerto.

El tooling soporta modo benchmark para rastrear tasas de aprobación y uso de tokens a través de actualizaciones de modelos, ejecución paralela multi-agente para evitar contaminación de contexto durante las pruebas, y un agente comparador que corre comparaciones A/B a ciegas del output con y sin el Skill aplicado.

El retorno compuesto

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

La estructura de carpetas es cómo moldean la ventana de contexto de Claude. Los Gotchas convierten los fracasos propios en conocimiento reutilizable. Los evals miden si ese conocimiento sigue siendo válido.

Escribir un SKILL.md toma diez minutos. Agregar Gotchas a partir de fallas reales, construir casos de eval e incluir scripts de validación toma cerca de diez horas. Esa inversión se recupera cada vez que el Skill corre. Armen uno esta noche. Para la mañana, habrá hecho trabajo que ustedes no tuvieron que hacer.