La mayoría de las habilidades que escriben las personas están equivocadas: 5 reflexiones tras la publicación de la metodología interna de Anthropic

Autor: AI Producto Aying

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 habilidades.

Las habilidades en realidad no son complicadas, pero realmente querer hacer una buena habilidad, creo que no es tan fácil.

Recuerdo que cuando las habilidades se pusieron de moda, a todos les encantaba crear habilidades de estilo literario, habilidades de escritura. Como si solo al incorporar su estilo de escritura, el modelo pudiera producir de manera estable en ese estilo.

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

Porque una habilidad de estilo literario puede contener solo unos pocos miles o incluso decenas de miles de palabras. Cuando se carga una habilidad, el contexto ocupa una gran parte. Cuando el contexto es grande, la capacidad de pensamiento del modelo tiende a disminuir.

Al final, a menudo aparece una situación: el estilo se aprende, 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 habilidades, les gusta incluir instrucciones operativas variadas. Qué hacer en el primer paso, qué en el segundo, qué en el tercero. Como resultado, al ejecutarse, el modelo no es estable.

Luego entendí lentamente que muchas tareas repetitivas en realidad son más adecuadas para consolidarse en scripts, en lugar de escribir instrucciones largas.

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

La esencia de una habilidad es hacer ingeniería de contexto. Cuándo deberías poner conocimientos en una habilidad, cuándo dividir en referencias, cuándo escribir en un script, cuándo usar gotchas para restringir el modelo, en realidad hay mucha experiencia en esto.

Al entender el principio de funcionamiento de las habilidades, al volver a ver esas habilidades excelentes, descubrirás que no resuelven el problema de las palabras clave, sino que abordan el contexto, la sedimentación de experiencia y la reutilización de capacidades.

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

#01 No pongas palabrería

La habilidad en realidad es sedimentar el «conocimiento tácito» en la organización. Por lo tanto, no repitas en la habilidad conocimientos que ya sabe. Lo verdaderamente valioso son esas informaciones que el modelo en realidad no conoce.

Dentro de Anthropic, suelen enfatizar que lo que realmente hay que escribir en una habilidad son los gotchas, es decir, los errores comunes.

Por ejemplo:

1. Esta tabla no debe ordenarse por created_at

2. Que staging devuelva 200 no significa que haya sido exitoso

3. request_id y trace_id son lo mismo

Porque esta información a menudo existe en la experiencia de los empleados. Así que hay que recordar cuál es la esencia de una habilidad.

Habilidad = poner por escrito la experiencia de los maestros.

A través de la habilidad, consolidar la experiencia dispersa en diferentes mentes.

#02 La habilidad en realidad es ingeniería de contexto

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

Una habilidad no es un archivo markdown, sino una carpeta. Para quienes han usado habilidades, esto suena como una tontería.

Pero estos días, reflexionando una y otra vez, me di cuenta lentamente: ellos quieren usar la forma de una carpeta para expresar la idea de ingeniería de contexto.

Veamos la estructura típica de una habilidad:

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

Cuando se llama a una habilidad, lo primero que lee el modelo es SKILL.md. Si llenamos toda la información en este archivo, rápidamente el contexto explotará.

Supongamos que esta es una habilidad para solucionar 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 esto se acumula en SKILL.md, cada vez que se llama a la habilidad, Claude tiene que releerlo.

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

Y la idea de Anthropic es completamente diferente.

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

Cuando necesita consultar casos históricos, revisa en examples; cuando necesita realizar acciones de diagnóstico, ejecuta scripts; y cuando genera informes finales, usa las plantillas en assets.

Todo el proceso se revela de forma progresiva.

Aquí hay una imagen que recomiendo mucho que 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 escribir habilidades, 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 de análisis desde cero.

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

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

Además, mediante scripts, la ejecución de la habilidad será más precisa y consumirá menos tokens.

Desde esta perspectiva, los scripts en las habilidades en realidad consolidan la capacidad organizacional. Cada script suele ser el resultado de muchas caídas y errores, y las mejores prácticas que el equipo ha resumido.

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

Por eso cada vez más creo que en las habilidades, las instrucciones y los scripts abordan problemas en niveles diferentes.

Las instrucciones ofrecen experiencia y juicio, los scripts ofrecen capacidad y ejecución.

Por ejemplo, en una habilidad de solució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 payment_events.

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

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

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

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

Muchas personas escriben la descripción de la habilidad de forma incorrecta por naturaleza.

Porque están acostumbrados a describir las funciones. Por ejemplo: PR Management Skill ayuda a los usuarios a monitorear el estado de PR, resolver problemas de CI, hacer merge automáticamente.

Pero el problema es que el modelo no busca habilidades por funciones, sino que cuando Claude Code se inicia, escanea todos los nombres y descripciones de habilidades.

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

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

La descripción en realidad cumple la función de enrutamiento de toda la habilidad.

En el mundo real, pocas personas dirían: «Ayúdame a usar una herramienta de gestión de PR». Es más probable que digan: «Ayúdame a vigilar este PR, o que el CI falló otra vez».

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

Incluso creo que se puede comprobar con un método muy simple.

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

Si no puede, probablemente todavía hay que seguir ajustando.

#05 Gestión y distribución de habilidades

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

Para un solo usuario, esto es muy simple. Escribir unas pocas habilidades, mantenerlas y actualizarlas uno mismo. Pero creo que la mayoría de los equipos enfrentará el mismo problema.

Cuando las habilidades pasan de unas pocas a decenas o incluso cientos, ¿cómo se gestionan? ¿Cómo se actualizan? ¿Cómo se distribuyen entre los miembros del equipo?

La experiencia de Anthropic en este aspecto creo que es muy valiosa.

En equipos pequeños, las habilidades siguen directamente el repositorio de código. En la carpeta .claude/skills del proyecto. Todos comparten las mismas habilidades y métodos de trabajo.

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

Cuando Claude Code inicia, escanea todos los nombres y descripciones de habilidades, y decide qué habilidad llamar según la tarea actual. Cuantas más habilidades, 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, al enfrentarse a este problema, su primera reacción suele ser establecer un proceso de aprobación. Quien cree una habilidad, primero envía una solicitud; tras revisión, pasa a la biblioteca oficial de habilidades. Nosotros también lo hicimos antes, pero era muy rígido. Por gestionar por gestionar.

Pero la organización de Anthropic es muy ligera.

Permiten que las nuevas habilidades se difundan primero en un pequeño grupo, que los colegas las instalen y prueben por sí mismos.

Si cada vez más personas las usan, significa que esa habilidad realmente resuelve un problema real. En ese momento, el autor puede enviarla al Marketplace oficial.

Por eso, no primero discuten si la habilidad tiene valor, sino que la dejan pasar por pruebas en escenarios reales. Cuantas más personas la usen, más natural será que pase a la fase oficial. Las habilidades que permanecen son, en realidad, las que el equipo realmente necesita.