Explicación de la función de habilidades de código de Claude: Qué hace y cómo usarla

Hola, soy Lena. Algo tranquilo pasó en cómo trabajaba con Claude* Code**** a finales del año pasado. No había planeado notarlo — solo intentaba dejar de repetirme. *En cada nueva sesión, me encontraba reexplicando las mismas cosas. Nuestras convenciones de formato de error. Cómo nos gusta que estén estructurados los mensajes de commit. Qué librerías de Python buscar primero. Claude lo procesaba todo, respondía adecuadamente y luego — en la siguiente sesión — se olvidaba de todo. No fue exactamente un fracaso. Fue simplemente... el mismo punto de partida, cada vez.

Luego empecé a mirar la función Habilidades de Código de Claude, y algo cambió ligeramente. ! [imagen] (https://cdn.z-image.ai/1774439693662-1.png)

¿Qué es la función de habilidades de código Claude?

Lo que SKILL.md realmente es

En su forma más simple, una habilidad es un directorio que contiene un archivo SKILL.md — una carpeta organizada de instrucciones, scripts y recursos que los agentes pueden descubrir y cargar dinámicamente para rendir mejor en tareas específicas.

El archivo tiene dos partes: YAML frontmatter en la parte superior (entre --- marcadores) y instrucciones de marcado debajo. El campo de nombre se convierte en el comando slash, y la descripción ayuda a Claude a decidir cuándo cargarlo automáticamente.

En la práctica, se ve así:

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Hmm... Vale. Así que no es magia. Es un archivo de texto estructurado que Claude lee cuando lo requiere.

Cómo difieren las habilidades de los prompts del sistema y las reglas del proyecto

Esta parte me pareció un poco confusa al principio.

A diferencia de los prompts — **instrucciones a nivel de conversación para tareas puntuales — las habilidades se cargan bajo demanda y eliminan la necesidad de proporcionar repetidamente la misma guía en varias conversaciones. La diferencia clave es cuándo cargan las cosas. Un prompt del sistema siempre está ahí. Una habilidad permanece silenciosa en el sistema de archivos y solo se contextualiza cuando Claude decide que es relevante para lo que estás haciendo.

Lo que hace interesante este diseño es que logra una expansión de prompts bajo demanda sin modificar el prompt del sistema central. Las habilidades son paquetes de conocimiento ejecutables que Claude carga solo cuando es necesario, ampliando las capacidades mientras mantiene el prompt principal ágil.

Eso me pareció una distinción significativa — aunque todavía no tengo del todo claro cómo Claude decide cuándo realmente entra en juego "relevante".

Cómo usar las habilidades de código Claude

Dónde colocar tu archivo SKILL.md

Las habilidades se descubren y cargan desde múltiples fuentes. Claude Code escanea la configuración del usuario (config/claude/skills/), la configuración del proyecto (.claude/skills/), las habilidades proporcionadas por complementos y las habilidades integradas para construir la lista de habilidades disponibles.

Entonces: las habilidades a nivel de usuario van en ~/.claude/skills/nombre-de-la-habilidad/SKILL.md. Las habilidades a nivel de proyecto van en .claude/skills/nombre-de-la-habilidad/SKILL.md dentro de tu repositorio. Cada habilidad necesita su propio subdirectorio con nombre. Las habilidades definidas en .claude/skills/ dentro de directorios añadidos mediante --add-dir se cargan automáticamente y son detectadas por la funcionalidad de detección de cambios en vivo, por lo que puedes editarlas durante una sesión sin reiniciar.

Esa última parte — ​editar durante una sesión sin reiniciar ​​— no lo esperaba. Significa que puedes ajustar una habilidad a mitad de tarea y ver qué cambios se producen. Eso parece digno de atención.

Qué tipo de instrucciones seguirá Claude

Los archivos de habilidades pueden contener cualquier instrucción, pero pensar en cómo deseas invocarlas ayuda a guiar qué incluir. El contenido de referencia añade conocimiento que Claude aplica a tu trabajo actual — convenciones, patrones, guías de estilo, conocimiento del dominio. El contenido de tarea le da a Claude instrucciones paso a paso para una acción específica, como despliegues, commits o generación de código.

También puedes agrupar archivos de soporte. Scripts que Claude puede ejecutar. Plantillas que puede rellenar. Documentación de referencia que carga solo cuando es necesario. Claude carga la información en etapas según sea necesario, en lugar de consumir todo el contexto desde el inicio — un patrón de divulgación progresiva. Por lo tanto, una habilidad puede ser mucho más rica que un solo archivo, sin sobrecargar la ventana de contexto cada vez.

Verificando que la habilidad se está aplicando

Esta parte todavía me resulta un poco confusa.

Según la documentación oficial de habilidades de Claude Code, el campo de descripción es lo que determina el activado automático — Claude lee todas las descripciones de habilidades disponibles al inicio y las usa para decidir cuándo invocar una habilidad. Las pruebas en el mundo real con más de 200 prompts muestran una variación significativa en la fiabilidad de activación. Las descripciones optimizadas adecuadamente pueden mejorar la activación del 20% al 50%. Añadir ejemplos la mejora aún más hasta un 90%.

Así que si una habilidad no se activa, la descripción suele ser lo primero que vale la pena revisar. Lenguaje más específico, condiciones de activación más explícitas. El repositorio de habilidades de Anthropic en GitHub lo señala directamente — Claude tiende a activarse menos de lo esperado, por lo que el lenguaje de la descripción se beneficia de ser algo explícito sobre cuándo activar.

Para qué son útiles las Habilidades

Codificar convenciones del proyecto

Aquí es donde empecé a ver el valor con más claridad. Si tu equipo tiene patrones específicos — cómo estructuras las respuestas de la API, cómo lucen tus objetos de error, cómo manejar flujos asíncronos — puedes poner todo eso en una habilidad una vez y dejar de explicarlo una y otra vez.

Construir una habilidad para un agente es como armar una guía de integración para un nuevo empleado. Esa metáfora me funcionó. No es una memoria permanente. Más bien es como una hoja de referencia a la que Claude puede recurrir.

Formato de salida repetible

Las habilidades basadas en tareas — las que se invocan con un comando de barra — son buenas para cosas como la generación de mensajes de commit, descripciones de PR, listas de verificación de despliegues. Cualquier cosa donde quieras una forma consistente en la salida, no solo una guía general.

Dar contexto específico del dominio a Claude

Las habilidades amplían las capacidades de Claude al empaquetar tu experiencia en recursos componibles, transformando agentes de propósito general en agentes especializados que se ajustan a tus necesidades. Para equipos que trabajan en dominios técnicos especializados — DSLs personalizados, herramientas internas, reglas de cumplimiento especializadas — esto empieza a verse realmente útil.

Lo que las habilidades no pueden hacer

Sin aprendizaje entre sesiones

Las habilidades no se actualizan por sí mismas. No observan qué funcionó ni revisan sus propias instrucciones. Lo que esté en SKILL.md cuando comienza una sesión es lo que Claude utiliza — hasta que lo editas manualmente. El blog de ingeniería de Anthropic sobre Agent Skills lo explica claramente: "Itera con Claude — mientras trabajas en una tarea con Claude, pídele que capture sus enfoques exitosos en la habilidad." Capturarlo es un paso humano. Claude no lo hace automáticamente.

Sin bucle de retroalimentación de ejecución

Si Claude ejecuta una habilidad y produce una salida incorrecta, la habilidad no se actualiza para reflejar eso. No hay ninguna señal que fluya de vuelta al conjunto de instrucciones. La misma orientación se aplicará la próxima vez, sin importar lo que haya pasado la vez anterior.

Sin compartir entre equipos o agentes

Las habilidades personalizadas son individuales para cada usuario; no se comparten a nivel organizacional ni pueden ser gestionadas centralmente por los administradores. Una habilidad que un desarrollador cree no se propaga automáticamente a los entornos de sus compañeros de equipo. Existe localmente o en un directorio de proyecto que debe compartirse manualmente.

Sigo pensando en esto. La capacidad de definir un comportamiento consistente del agente es real, pero el problema de la distribución sigue ahí.

Qué viene después de las habilidades estáticas

De instrucciones basadas en archivos a capacidades validadas y heredables

La función de habilidades resuelve algo real: el problema de la repetición. Dejas de volver a explicar el contexto. Comienzas a codificarlo.

Pero hay un vacío que sigo notando. Una reparación exitosa, un patrón de depuración arduamente conseguido, una secuencia de instrucciones que finalmente funcionó de manera confiable: estas experiencias aún no se transmiten. Permanecen en la sesión, o tal vez se integren manualmente en un archivo SKILL.md si alguien recuerda hacerlo.

Hay una cuestión más amplia debajo de esto que todavía estoy intentando formular. Algo sobre la diferencia entre instrucciones dadas y comportamiento validado a través de muchos agentes. Las habilidades son instrucciones dadas. Están bien diseñadas, son composables y útiles. Pero siguen siendo artefactos estáticos: creados por humanos, mantenidos manualmente, con alcance local.

¿Cómo sería si un enfoque exitoso pudiera ser destacado, verificado y puesto a disposición de otros agentes que enfrentan problemas similares? Esa es un tipo diferente de pregunta de infraestructura, una que el formato de habilidades no aborda y probablemente no intenta abordar.

…Seguiré pensando en esto.

Preguntas frecuentes

1. ¿Qué es la función de habilidades en Claude Code? La función de habilidades de Claude Code te permite extender el comportamiento de Claude a través de archivos SKILL.md estructurados, cada uno conteniendo frontmatter YAML e instrucciones en markdown que Claude carga dinámicamente cuando una tarea coincide con la descripción de la habilidad.
2. ¿Cómo creo un archivo SKILL.md para Claude Code? Crea una carpeta en .claude/skills/nombre-de-tu-habilidad/, luego agrega un archivo SKILL.md dentro de ella. Comienza con el frontmatter YAML (se requieren nombre y descripción), seguido de tus instrucciones en markdown. El repositorio de habilidades de Anthropic incluye un skill de plantilla como punto de partida.
3. ¿Persisten las habilidades de Claude Code entre sesiones? El archivo persiste. La memoria de Claude al aplicarlo no. Cada sesión, Claude vuelve a leer la descripción de la habilidad e instrucciones desde cero. No hay aprendizaje entre sesiones incorporado.
4. ¿Puedo compartir habilidades de Claude Code con mi equipo? Puedes compartir los directorios de habilidades manualmente, a través de la carpeta .claude/skills/ de tu repositorio, o mediante herramientas como el estándar abierto Agent Skills que soporta portabilidad entre plataformas. Pero actualmente no existe sincronización organizacional automática.
5. ¿Cuál es la diferencia entre las habilidades de Claude Code y las reglas del proyecto? Las reglas del proyecto (como CLAUDE.md) configuran el comportamiento general de un proyecto. Las habilidades son paquetes modulares de capacidades específicas para tareas: se cargan condicionalmente según lo que Claude esté haciendo, en lugar de estar siempre activas en el contexto. Piensa en CLAUDE.md como instrucciones ambientales y en las habilidades como experiencia bajo demanda.