Claude Code Skills: Guía de Construir, Compartir y Ampliar
Hola, chicos, Lena está aquí. Algo cambió silenciosamente a finales de 2025. No me di cuenta de todo de golpe — llegó despacio, como la mayoría de los cambios reales.
Había estado observando cómo Claude Code manejaba tareas repetidas entre proyectos. El patrón me resultaba familiar: las mismas instrucciones, reescritas de forma ligeramente diferente cada vez. El mismo contexto, reexplicado. Empezó a sentir que faltaba algo — no en el modelo, sino en la capa entre el modelo y la obra.
Esa capa ya tiene nombre. Se llama Habilidades de Código Claude.
! [imagen] (https://cdn.z-image.ai/1774441608333-11.png)
¿Qué son las habilidades de código de Claude?
En el nivel más simple, una habilidad Claude Code es una carpeta. Dentro de esa carpeta hay un archivo llamado SKILL.md. Cuando Claude Code encuentra esa carpeta, lee el archivo, carga las instrucciones en contexto y ajusta su comportamiento en consecuencia.
Sigo volviendo a esa descripción porque suena casi demasiado simple. Y, sin embargo, las implicaciones —una vez que te sientas con ellas— son mayores de lo que parecen a primera vista.
Las habilidades no son prompts que pegas al inicio de cada conversación. Son paquetes de comportamiento reutilizables que Claude descubre y aplica automáticamente. Lo instalas una vez. Claude capta el contexto siempre que es relevante — sin que se lo recuerden.
El formato SKILL.md — Cómo funciona
Cada habilidad comienza con la misma estructura de dos partes. SKILL.md es un archivo markdown que sigue una estructura de dos partes: frontmatter y contenido. El frontmatter configura cómo se ejecuta la habilidad (permisos, modelo, metadatos), mientras que el contenido markdown le dice a Claude qué hacer.
Un ejemplo mínimo se ve algo así:
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude will follow when this skill is active]
El campo name se convierte en el comando de barra. El campo description es lo que Claude lee al decidir si cargar la habilidad en absoluto. La descripción es fundamental para la selección de habilidades: Claude la usa para elegir la habilidad adecuada entre potencialmente 100+ habilidades disponibles. Tu descripción debe proporcionar suficiente detalle para que Claude sepa cuándo seleccionar esta habilidad, mientras que el resto de SKILL.md proporciona los detalles de implementación.
Esa última parte es fácil de subestimar. Me equivoqué en mis primeros intentos: escribí descripciones que eran técnicamente precisas pero con un comportamiento muy vagas. La habilidad cargaba en los momentos equivocados, o no se cargaba en absoluto. La descripción no es un metadato. Es una decisión de enrutamiento.
Puedes leer la documentación oficial de Claude Code Skills para un desglose completo de la especificación.
! [imagen] (https://cdn.z-image.ai/1774441610567-22.png)
Qué tipos de comportamientos puedes codificar
Aquí es donde se pone interesante. Las habilidades no se limitan a instrucciones de texto. Cada habilidad es un directorio que puede incluir un archivo principal SKILL.md, plantillas para que Claude complete, ejemplos de resultados mostrando el formato esperado y scripts que Claude puede ejecutar.
En la práctica, eso significa que puedes codificar:
- Convenciones de codificación — cómo tu equipo nombra funciones, estructura pruebas, maneja errores
- Patrones de flujo de trabajo — procesos de múltiples pasos que Claude debe seguir al generar informes o procesar archivos
- Scripts ejecutables — lógica de validación, transformaciones de archivos, llamadas a APIs externas que se ejecutan de manera determinista
- Documentos de referencia — especificaciones detalladas que Claude lee bajo demanda, sin sobrecargar cada sesión
La idea clave de diseño: cuando se activa una habilidad, Claude utiliza bash para leer SKILL.md desde el sistema de archivos, llevando sus instrucciones a la ventana de contexto. Si esas instrucciones hacen referencia a otros archivos, Claude también los lee. Cuando las instrucciones mencionan scripts ejecutables, Claude los ejecuta y recibe solo el resultado, nunca el código del script dentro del contexto.
Ese es un punto sutil pero importante. La habilidad se carga de manera perezosa. Puedes incluir un documento de referencia de 50 páginas dentro de una habilidad, y Claude solo tomará lo que realmente necesita.
Construyendo tu primera habilidad en Claude Code
Seré honesto: mi primera habilidad fue mala. No estaba rota, simplemente... no era precisa. Se cargaba demasiado ampliamente, sus instrucciones competían con la conversación, y pasaba más tiempo explicando lo que quería que si simplemente lo hubiera escrito.
Esto es lo que haría diferente.
Ubicación y formato de archivos
Para Claude Code, las habilidades se guardan en .claude/skills/ dentro de tu directorio de proyecto, o en ~/.claude/skills/ para habilidades personales que se aplican globalmente. Claude Code soporta solo Habilidades Personalizadas — crea habilidades como directorios con archivos SKILL.md.
El nombre de la carpeta se convierte en la identidad de la habilidad. Mantén el nombre en minúsculas, usa guiones. Dentro:
my-skill/
├── SKILL.md ← required
├── examples/ ← optional but helpful
│ └── sample.md
└── scripts/ ← optional
└── validate.sh
El frontmatter de SKILL.md requiere dos campos: name y description. El campo name debe usar solo letras minúsculas, números y guiones. Siempre escribe la descripción en tercera persona — la descripción se inyecta en el prompt del sistema, y un punto de vista inconsistente puede causar problemas de descubrimiento.
Comprobando que tu habilidad se está aplicando
Esto me confundió al principio. No hay una notificación explícita de "habilidad cargada" en la interfaz. Lo que he encontrado que funciona: preguntar directamente a Claude. "¿Qué habilidades tienes disponibles?" generalmente muestra la lista. También puedes comprobar si el comportamiento de Claude cambia con indicaciones específicas de la tarea que deberían activar la habilidad.
La prueba más confiable es de comportamiento: ejecuta la misma tarea con la habilidad activa y sin ella. Si el patrón de salida cambia en la dirección que codificaste, la habilidad está funcionando. Entender el mecanismo de activación ayuda a diseñar mejores habilidades. Las habilidades aparecen en la lista de habilidades disponibles de Claude con su nombre y descripción, y Claude decide si consultar una habilidad según esa descripción. Claude solo consulta habilidades para tareas que no puede manejar fácilmente por sí mismo: consultas simples de un solo paso pueden no activar una habilidad incluso si la descripción coincide.
Errores Comunes en el Diseño de Habilidades
La guía de mejores prácticas para la creación de habilidades de Anthropic cubre esto bien, pero los errores que he visto con más frecuencia:
- Descripciones vagas — Claude no puede redirigir a una habilidad que no entiende con precisión
- SKILL.md sobrecargado — intentar codificar todo en un solo archivo; utiliza referencias para los detalles
- Sin ejemplos — habilidades sin ejemplos concretos producen resultados inconsistentes
- Instrucciones obsoletas — no incluyas información que se vuelva desactualizada; las instrucciones específicas de versión deben estar en secciones desplegables o claramente fechadas
Compartir Habilidades Entre Proyectos y Equipos
Aquí es donde las cosas se vuelven realmente útiles, y también donde las limitaciones actuales se hacen visibles.
Limitaciones Actuales de Compartir SKILL.md
Las habilidades se basan en archivos. Eso significa que compartirlas requiere distribución de archivos: carpetas zip, repositorios Git, copiado manual. El modelo de distribución actual requiere que los usuarios individuales descarguen la carpeta de la habilidad y la coloquen en el directorio de habilidades de Claude Code. Las habilidades a nivel de organización pueden ser implementadas en todo el espacio de trabajo por los administradores — esto se lanzó en diciembre de 2025 — con actualizaciones automáticas y gestión centralizada.
Eso es una mejora significativa. Pero aún significa que la habilidad existe como un artefacto estático. Cuando el flujo de trabajo subyacente que codifica cambia, la habilidad no se actualiza automáticamente. Alguien tiene que mantenerla.
En diciembre de 2025, Anthropic lanzó la especificación Agent Skills como un estándar abierto, y OpenAI adoptó el mismo formato para Codex CLI. Las habilidades son invocadas por el modelo: la IA decide automáticamente cuándo usarlas según el contexto. Esa interoperabilidad es real y valiosa. Una habilidad que construyas para Claude Code puede, en principio, ejecutarse en Cursor u otros entornos compatibles. Puedes explorar el repositorio de skills de Anthropic en GitHub para ver ejemplos contribuidos por la comunidad.
Cómo se Ve una Capa de Compartición Entre Agentes
Esta es la parte que todavía estoy tratando de resolver.
En este momento, una habilidad es creada por un humano, revisada por un humano y distribuida manualmente. El agente la ejecuta pero no la mejora. No aprende de los resultados, no propaga variantes exitosas, no alerta cuando las instrucciones se han desviado de lo que realmente funciona.
Una verdadera capa de compartición entre agentes necesitaría algo más: validación de ejecución, puntuación de calidad, linaje de versiones. El SKILL.md estático captura bien la intención. No captura el resultado.
No estoy seguro de haber visto ese problema resuelto de manera limpia en ningún lugar todavía.
El Tope: Donde las Habilidades de Claude Code Dejan de Funcionar
Archivos Estáticos vs. Aprendizaje Adaptativo
Las habilidades son instrucciones. No observan su propio desempeño. Si una habilidad codifica un patrón de depuración que fue efectivo hace seis meses pero que desde entonces se ha vuelto menos fiable debido a actualizaciones del modelo o cambios en la API, la habilidad no se dará cuenta. Tú sí, eventualmente.
Las habilidades son documentos vivos. Planea iterar según su desempeño a lo largo del tiempo. Ese es un buen consejo, pero coloca toda la carga de la iteración en el autor. El agente no puede participar en mejorar la instrucción que está siguiendo.
Sin Validación de Ejecución, Sin Bucle de Reparación
Cuando una habilidad se ejecuta y el resultado es incorrecto, nada en el mecanismo de la habilidad lo detecta. Claude ejecuta lo que dice el SKILL.md. Si el resultado no coincide con la intención, el bucle no se cierra automáticamente.
Esto es menos problemático para habilidades que codifican convenciones estables (estilo de código, estructura de documentos) y más problemático para habilidades que codifican flujos de trabajo dinámicos donde la corrección depende de la tarea.
Sin Red de Reutilización
Las habilidades hoy en día son o locales (tuyas) o públicas (compartidas en GitHub). No existe una capa ambiental donde una solución exitosa a una clase de problemas —probada, validada y rastreada por versión— se vuelva descubrible y heredable por otros agentes que trabajan en problemas similares.
El mercado comunitario de SkillsMP es un gesto temprano en esta dirección. Es útil para descubrir lo que otros han construido. Pero las habilidades que indexa siguen siendo archivos estáticos. No llevan registros de auditoría. No saben cuántas veces se han aplicado ni con qué resultados.
Lo que viene después de las habilidades
De instrucciones estáticas a capacidades validadas, heredables y intercambiables
Llevo un tiempo dándole vueltas a esta pregunta.
Las habilidades de Claude Code resuelven un problema real: hacen que el comportamiento de los agentes sea repetible y transferible. Eso no es poca cosa. Antes de las habilidades, el contexto tenía que restablecerse en cada sesión. Ahora ya no.
Pero una habilidad sigue siendo un artefacto humano. Captura lo que alguien pensó que funcionaba. No lleva pruebas de qué funcionó realmente, en qué condiciones, con qué modos de fallo.
La siguiente capa — sea cual sea la que se convierta — probablemente se parezca menos a un formato de archivo y más a una capacidad con procedencia. Algo que diga: este enfoque se intentó en estas condiciones, tuvo éxito a este ritmo, falló en estos casos límite, fue revisado por estos autores y ha sido aplicado por estos agentes en situaciones comparables.
Eso es un tipo de infraestructura diferente a un archivo markdown.
Todavía no sé qué pensar de esa brecha. Pero no parece aleatorio. Parece lo siguiente a ver.
! [imagen] (https://cdn.z-image.ai/1774441614198-55.png)
Preguntas frecuentes
- ¿Qué es un archivo SKILL.md en Claude Code?
SKILL.md contiene las instrucciones principales y es necesario para cada habilidad de Claude Code. Sigue una estructura de dos partes: frontmatter YAML que indica a Claude cuándo usar la habilidad, y contenido de markdown con instrucciones que Claude sigue cuando se invoca la habilidad. Piénsalo como un documento de incorporación — excepto que el agente nunca lo olvida.
- ¿Cómo escribo una habilidad de Código Claude?
Empieza con el frontmatter: name (minúsculas, solo guiones) y description (tercera persona, específico sobre cuándo invocar). Luego escribe instrucciones claras e imperativas en el cuerpo del markdown. Añade archivos de apoyo — ejemplos, scripts, referencias — solo cuando realmente mejoren el comportamiento. Prueba comparando la salida de la tarea con y sin la habilidad activa. Consulta las mejores prácticas de creación de habilidades de Anthropic para una guía detallada.
- ¿Se pueden compartir las habilidades de Claude Code entre miembros del equipo?
Los administradores de la organización pueden desplegar habilidades en todo el espacio de trabajo, con actualizaciones automáticas y gestión centralizada; esto se lanzó en diciembre de 2025. Para compartir de código abierto, GitHub es el canal de distribución actual. El estándar abierto Agent Skills significa que las habilidades creadas para Claude Code también pueden funcionar en otras herramientas compatibles. La interoperabilidad es real; una red centralizada de reutilización con historial de ejecución sigue siendo un problema abierto.
Seguiré observando cómo evoluciona esto. Está pasando algo aquí, solo que aún no puedo ver completamente dónde terminará.
