Qué hace que una Skill de Claude funcione realmente, según la propia guía de Anthropic
La propia guía de Anthropic para crear Skills trata, sobre todo, de qué conviene omitir: una descripción de dos líneas, un SKILL.md breve y archivos de referencia anidados a no más de un nivel.
Respuesta rápida
¿Qué dice la documentación de Anthropic que hace que una Skill de Claude funcione realmente?
El éxito o el fracaso de una Skill depende de un solo campo: la descripción, escrita en tercera persona, que indique qué hace y cuándo debe utilizarse. Mantenga SKILL.md por debajo de las 500 líneas y los archivos de referencia a un solo nivel de profundidad, pruébela con todos los modelos con los que tenga previsto usarla y nunca instale una Skill de una fuente que no sea de confianza.
Claves
- Claude decide qué Skill cargar basándose únicamente en el campo de descripción, antes de leer cualquier otra cosa: una descripción imprecisa hace que la Skill nunca sea seleccionada.
- Las Skills se cargan en tres etapas y solo la primera —unos 100 tokens de metadatos— está siempre en contexto; el cuerpo se carga al activarse y los archivos incluidos, únicamente cuando se leen.
- Mantenga todos los archivos de referencia a un solo enlace de distancia de SKILL.md. Claude puede leer parcialmente una cadena profundamente anidada y pasar por alto el resto.
- Escriba scripts exactos y con poco margen de maniobra para las operaciones delicadas, e instrucciones flexibles para las tareas que requieren criterio: adaptar el formato a la tarea importa más que la extensión.
- Una Skill subida a claude.ai no aparece en la API ni en Claude Code. Cada entorno requiere una instalación independiente.
Una Skill es una carpeta que Claude puede abrir en mitad de una tarea: un archivo SKILL.md y, opcionalmente, scripts y material de referencia. La idea es que Claude solo consume recursos por aquello que utiliza: la mayor parte de una Skill permanece fuera de la ventana de contexto hasta que algún elemento de la conversación la requiere realmente. La propia guía de creación de Anthropic dedica menos tiempo a explicar qué debe incluirse en una Skill que qué debe dejarse fuera, y conviene reproducir directamente la estructura de esos consejos.
El campo de descripción lo decide todo
Antes de abrir una Skill, Claude solo ve una cosa: el campo description del frontmatter YAML, limitado a 1.024 caracteres. Las indicaciones de Anthropic son concretas: debe escribirse en tercera persona ("Procesa archivos de Excel…", no "Puedo ayudarle con…") e indicar tanto qué hace la Skill como cuándo debe utilizarse. Cuando puede haber más de cien Skills disponibles a la vez, esta frase plantea un problema de correspondencia: Claude elige entre las candidatas basándose únicamente en la descripción, por lo que una formulación imprecisa puede hacer que la Skill nunca sea seleccionada, sin que aparezca ningún error que explique el motivo.
El campo name es más breve, pero tiene sus propias reglas: un máximo de 64 caracteres, únicamente letras minúsculas, números y guiones, y no puede contener "claude" ni "anthropic". Anthropic recomienda nombres en gerundio (procesando-pdf, analizando-hojas-de-calculo) en lugar de otros imprecisos (ayudante, utilidades).
Tres niveles, tres costes
Las Skills se cargan por etapas, y el modelo de costes explica por qué el formato tiene esta estructura:
Esta estructura también explica los límites de tamaño: Anthropic recomienda que el cuerpo de SKILL.md no supere los 5.000 tokens ni las 500 líneas. Si rebasa esas cifras, traslade el contenido a un archivo independiente y enlácelo: no consume nada hasta que Claude lo abre.
Mantenga las referencias a un solo nivel de profundidad
Un archivo que Claude solo lee parcialmente es peor que uno que no lee en absoluto. Las indicaciones de Anthropic advierten de que Claude puede limitarse a examinar superficialmente una cadena de referencias profundamente anidada —en la práctica, ejecutando algo parecido a head -100— en vez de leerla entera. Por eso, cualquier contenido situado a más de un enlace de SKILL.md corre el riesgo de quedar incompleto. Si un archivo de referencia supera las 100 líneas, incluya un índice al principio: así, incluso una lectura parcial mostrará a Claude todo el alcance del contenido disponible.
Adapte las instrucciones a lo que puede salir mal
No todas las Skills necesitan el mismo tipo de instrucciones. Anthropic lo plantea en términos de "grados de libertad": una tarea que exige mucho criterio —resumir un documento o redactar un correo electrónico— puede describirse con un lenguaje flexible y un alto grado de libertad, mientras que una operación delicada o que debe ser uniforme —una migración de base de datos o una secuencia específica de llamadas a una API— debe definirse mediante un script exacto y con poco margen de maniobra. Redactar instrucciones vagas para este último tipo de operación es donde las Skills suelen fallar silenciosamente.
Pruebe el punto de partida antes de redactar el tratado
El orden recomendado es fácil de pasar por alto y también es fácil lamentar haberlo hecho: ejecute al menos tres situaciones de prueba reales con Claude antes de redactar documentación extensa, para saber qué hace mal Claude sin la Skill. De lo contrario, resulta fácil dedicar párrafos enteros a resolver un problema que Claude en realidad no tenía. Anthropic también recomienda probar la Skill terminada con todos los modelos en los que tenga previsto ejecutarla: Haiku, Sonnet y Opus no se comportan de manera idéntica, y unas instrucciones suficientemente concisas para Opus pueden ser demasiado escuetas para Haiku.
Trátela como si instalara software
Anthropic lo afirma sin rodeos: utilice únicamente Skills escritas por usted o procedentes directamente de Anthropic. Una Skill puede ordenar a Claude que utilice indebidamente una herramienta o extraiga datos, y no existe un aislamiento que haga segura de forma predeterminada una Skill que no sea de confianza. Una carpeta con archivos Markdown y scripts que usted no ha escrito sigue siendo código que está a punto de permitir que ejecute un agente.
Compruebe la fecha. El propio documento de buenas prácticas de Anthropic desaconseja incorporar expresiones sujetas al paso del tiempo, como "antes de agosto de 2025, utilice X": el contenido de las Skills no se actualiza automáticamente, y la misma advertencia se aplica a este artículo. Consulte directamente la documentación enlazada si los detalles anteriores sobre la disponibilidad en cada entorno han cambiado desde entonces.
Preguntas frecuentes
- ¿Qué extensión debería tener realmente un SKILL.md?
- Las propias indicaciones de Anthropic recomiendan menos de 500 líneas para el cuerpo principal. Todo contenido adicional debería trasladarse a un archivo independiente enlazado, que solo se carga cuando Claude lo abre realmente.
- ¿Debo redactar la descripción de forma distinta al resto del archivo?
- Sí. Debe estar escrita en tercera persona e indicar tanto qué hace la Skill como cuándo debe utilizarse: esa frase es lo único que Claude ve antes de decidir si abre la Skill.
- ¿Una Skill que subo a claude.ai está disponible cuando utilizo la API?
- No. Las Skills se suben por separado en cada entorno: claude.ai (por usuario), la API de Claude (para todo el espacio de trabajo mediante /v1/skills) y Claude Code (una carpeta en el sistema de archivos). No existe sincronización automática entre ellos.
- ¿Es seguro instalar Skills de terceros?
- La propia documentación de Anthropic aconseja tratar la instalación de una Skill como la de cualquier software: una Skill puede ordenar a Claude que utilice indebidamente herramientas o extraiga datos, por lo que solo deben emplearse las escritas por uno mismo o las procedentes de Anthropic.
Fuentes
- Agent Skills — Anthropic
- Skill authoring best practices — Anthropic
- anthropics/skills — Anthropic