Anthropic finalmente ha hecho pública su metodología interna de habilidades

Leí un blog del equipo de Anthropic titulado «Lecciones de construir Claude Code: Cómo usamos habilidades». Esta debería ser la práctica más profunda que he visto hasta ahora sobre Skill.

Skill en realidad no es algo complicado, pero realmente querer hacer un Skill bien, creo que no es tan fácil.

Recuerdo que cuando Skill se popularizó, a todos les encantaba crear Skills con diferentes estilos de escritura, Skills de escritura. Como si solo al poner su propio estilo en el Skill, el modelo pudiera mantener esa forma de salida de manera estable.

Pero luego probé un poco y descubrí que muchas veces simplemente no funciona.

Porque un estilo de escritura en un Skill puede requerir solo unos pocos miles o incluso decenas de miles de palabras. Cuando cargas un Skill, el contexto ocupa una gran parte. Cuando el contexto se vuelve muy grande, la capacidad de pensamiento del modelo en realidad disminuye.

Al final, suele ocurrir lo siguiente: se aprende el estilo, pero el contenido se vuelve superficial, y la capacidad de análisis también se debilita.

Otra situación común.

Muchas personas al escribir Skills, les gusta meter instrucciones operativas variadas. Qué hacer en el paso uno, qué en el paso dos, qué en el paso tres. Como resultado, al ejecutarlo, el modelo no es estable.

Luego entendí lentamente que muchas de estas tareas repetitivas son más adecuadas para consolidarlas en un Script, en lugar de escribir instrucciones largas y detalladas.

Después de leer este artículo de Anthropic, mi mayor impresión es que muchas personas en realidad están usando Skills, pero quizás no comprenden realmente qué es un Skill.

Esencialmente, un Skill es ingeniería de contexto. Cuándo deberías poner conocimientos en un Skill, cuándo dividir en Referencias, cuándo escribir un Script, cuándo usar Gotchas para restringir al modelo, en realidad hay mucha experiencia en esto.

Una vez que entiendes cómo funciona un Skill, al volver a mirar esos Skills excelentes, verás que no resuelven principalmente el problema de las instrucciones, sino que abordan el contexto, la sedimentación de experiencia y la reutilización de capacidades.

Si quieres profundizar en el estudio de Skills, recomiendo especialmente leer dos artículos:

#01 No hagas palabrería

Esencialmente, un Skill es la sedimentación del «conocimiento tácito» en la organización. Por eso, en un Skill no debes repetir conocimientos básicos que ya se saben. Lo que realmente tiene valor son esas informaciones que el modelo en realidad no conoce.

Dentro de Anthropic, suelen enfatizar que lo que hay que escribir en un Skill son los Gotchas, es decir, los errores comunes o trampas en las que se suele caer.

Por ejemplo:

1. Esta tabla no debe ordenarse por created_at

2. Que staging devuelva 200 no significa que haya tenido éxito

3. request_id y trace_id son lo mismo

Porque esta información a menudo está en la experiencia de los empleados. Por eso, hay que recordar qué es esencial en un Skill.

Skill = poner por escrito la experiencia de los veteranos.

A través de Skills, se sedimentan las experiencias dispersas en diferentes mentes.

#02 Skill en realidad es ingeniería de contexto

Este quizás sea uno de los puntos más profundos de Anthropic.

Un Skill no es un archivo markdown, sino una carpeta. Para quienes han usado Skills, esto puede sonar absurdo.

Pero estos días, reflexionando, me di cuenta lentamente: ellos quieren usar la estructura de carpeta para expresar la filosofía de la ingeniería de contexto.

Veamos otra vez la estructura típica de un Skill:

skill/  ├── SKILL.md  ├── references/ (explicaciones detalladas, referencias API, condiciones límite)  ├── scripts/ (scripts ejecutables)  ├── examples/ (ejemplos)  ├── assets/ (plantillas, imágenes, materiales fijos)

Cuando se llama a un Skill, lo primero que lee el modelo es SKILL.md. Si metemos toda la información en ese archivo, rápidamente el contexto explotará.

Supongamos que este es un Skill para resolución de problemas de pagos, que incluye tanto códigos de error de Stripe, casos históricos, scripts de diagnóstico y plantillas de informes finales.

Si todo ese contenido se acumula en SKILL.md, cada vez que se llama al Skill, Claude tiene que releerlo completo.

Incluso si el usuario solo quiere entender el significado de un código de error, o solo quiere verificar por qué un estado de pago no se actualiza, mucha información que en realidad no se necesita, también se incluirá en el contexto.

Pero la idea de Anthropic es completamente diferente.

SKILL.md funciona más como una página de navegación. Su función es decirle al modelo que, cuando encuentre un error de Stripe, busque en references la explicación correspondiente.

Cuando necesita consultar casos históricos, va a examples. Cuando necesita realizar acciones de diagnóstico, ejecuta scripts. Y cuando genera el informe final, usa las plantillas en assets.

Todo el proceso es una exposición progresiva.

La siguiente imagen, la recomiendo mucho que la guarden.

#03 Usa scripts siempre que puedas

No hagas que el modelo desperdicie su limitado contexto y capacidad de razonamiento en tareas repetitivas. Delega esas tareas a scripts.

Por ejemplo, muchas personas al crear Skills, lo hacen así:

1. Consultar datos de registro; 2. Consultar datos de pago; 3. Calcular tasa de conversión; 4. Analizar causas de anomalías.

Este método, por supuesto, funciona. El modelo puede hacerlo. Pero cada vez que se ejecuta, tiene que recorrer todo el proceso desde cero.

Consultar datos, organizar datos, manejar diferentes casos límite, esas tareas en realidad son repetitivas.

Dado que estas capacidades ya han sido verificadas muchas veces, ¿por qué hacer que el modelo las vuelva a inventar? Mejor proporcionar directamente un script específico.

Además, usando scripts, la ejecución del Skill será más precisa y también ahorrará tokens.

Desde esta perspectiva, los Scripts en un Skill en realidad representan la sedimentación de capacidades organizacionales. Cada script suele ser el resultado de muchas experiencias y errores pasados, resumidos en mejores prácticas.

Al consolidar estas capacidades, Claude puede trabajar siempre sobre esas experiencias, en lugar de empezar desde cero cada vez.

Por eso cada vez estoy más convencido de que en un Skill, Instructions y Scripts abordan problemas en niveles diferentes.

Las Instructions ofrecen experiencia y juicio, los Scripts ofrecen capacidades y ejecución.

Por ejemplo, en un Skill de resolución de problemas de pagos, podría haber una instrucción así:

Si Stripe devuelve 200, no asumas que el pago fue exitoso, sino verifica en la tabla payment_events.

Esto sería una Instruction, porque es experiencia. La función check_payment_events() sería un Script, porque es una capacidad de ejecución.

Si solo hay Script, el modelo sabe cómo consultar, pero quizás no sabe por qué.

Si solo hay Instructions, el modelo sabe qué hacer, pero cada vez tiene que volver a implementarlo. Ambas cosas son necesarias.

#04 La descripción funciona como una regla de enrutamiento

Muchos escriben la descripción de Skills de manera incorrecta por naturaleza.

Porque suelen centrarse en describir funciones, por ejemplo: PR Management Skill ayuda a monitorear estados de PR, gestionar CI, hacer merge automáticamente.

Pero el problema es que el modelo no busca Skills por funciones, sino que al arrancar Claude Code, primero escanea los nombres y descripciones de todos los Skills.

Luego, en función del problema actual del usuario, decide qué Skill cargar.

Por eso, lo más importante en la descripción no es qué puede hacer ese Skill, sino en qué situaciones debe cargarse.

La descripción en realidad cumple la función de enrutamiento del Skill.

En el mundo real, pocos dirían: «Ayúdame a llamar a una herramienta de gestión de PR». Es más probable que digan: «Revisa este PR», «El CI falló», etc.

Por eso, una buena descripción debe describir la intención del usuario, no solo listar funciones.

Incluso puedo usar un método muy simple para verificarlo.

Después de escribir la descripción, elimina toda la Skill y solo conserva esa línea. Luego pregúntate: ¿el modelo, al ver la pregunta del usuario, puede saber cuándo debe cargar este Skill?

Si no puede, probablemente todavía hay que ajustarla.

#05 Gestión y distribución de Skills

Otra cuestión es la gestión de Skills.

Para un usuario individual, esto es sencillo: crear unos Skills, mantener y actualizar. Pero creo que la mayoría de los equipos enfrentará el mismo problema.

Cuando los Skills pasan de unos pocos a decenas o cientos, ¿cómo gestionarlos? ¿Cómo actualizarlos? ¿Cómo distribuir a los miembros del equipo?

La experiencia de Anthropic en esto es muy valiosa.

En equipos pequeños, los Skills simplemente siguen el repositorio de código. En la carpeta .claude/skills del proyecto. Todos comparten los mismos Skills y métodos de trabajo.

Pero a medida que aumenta la cantidad de Skills, surge un nuevo problema.

Al arrancar Claude Code, escanea todos los nombres y descripciones de Skills, y decide qué Skill usar según la tarea. Cuantos más Skills, mayor será el costo de enrutamiento.

Por eso, Anthropic empezó a crear un Marketplace. Pero lo más interesante es cómo gestionan ese Marketplace.

Muchas empresas, ante este problema, primero establecen un proceso de aprobación. Quien cree un Skill, lo somete a revisión; tras aprobarse, se añade a la biblioteca oficial de Skills. Nosotros también lo hicimos, pero era muy rígido. Por gestionar por gestionar.

Pero la organización de Anthropic es muy ligera.

Permiten que los nuevos Skills se difundan primero en un entorno reducido, que los colegas los instalen y prueben por sí mismos.

Si cada vez más personas los usan, significa que realmente resuelven un problema. En ese momento, el autor puede enviarlo al Marketplace oficial.

Por eso, no discuten primero si el Skill tiene valor, sino que dejan que pase la prueba en escenarios reales. Cuanto más se use, más entra en el sistema oficial. Los Skills que permanecen son los que el equipo realmente necesita.