Explicación de las Habilidades de Claude: SKILL.md vs Capacidad del Agente
Hola, soy Lena. Algo se sintió un poco extraño la primera vez que configuré un archivo SKILL.md. No estaba mal, simplemente no era exactamente lo que esperaba. Había leído las instrucciones, colocado el archivo en el directorio correcto, y *Claude lo reconoció. Pero luego me empecé a preguntar: ¿exactamente qué le había dado? ¿Conocimiento? ¿Un hábito? ¿Algo que pudiera transmitir?*
He estado reflexionando sobre esa pregunta por un tiempo. Estas son algunas observaciones.
¿Qué Son las Habilidades de Claude?
Las habilidades de Claude son paquetes de capacidades modulares y reutilizables — carpetas organizadas que proporcionan a los agentes Claude instrucciones específicas de dominio, contexto y scripts opcionales para trabajar. El núcleo de cada habilidad es un archivo SKILL.md.
Si estás construyendo con Claude Code o la API de Claude, probablemente este sea un patrón que ya hayas encontrado, o que encontrarás pronto.
Cómo Funciona SKILL.md
Cada habilidad vive en un directorio. El archivo SKILL.md dentro tiene dos partes: un bloque de YAML frontmatter en la parte superior y un cuerpo en markdown debajo.
El frontmatter es mínimo. Le dice a Claude el nombre de la habilidad y cuándo usarla — una breve descripción que Claude lee al inicio. El cuerpo en markdown es donde viven las instrucciones reales: qué hacer, cómo formatear la salida, qué casos límite vigilar, qué archivos de soporte cargar.
Al inicio, el agente precarga el nombre y la descripción de cada habilidad instalada en su prompt de sistema. Estos metadatos son el primer nivel de divulgación progresiva: proporcionan la información suficiente para que Claude sepa cuándo se debe usar cada habilidad, sin cargarla toda en el contexto.
Esa parte me pareció realmente considerada. Claude no lee todo el archivo de la habilidad al inicio — solo el frontmatter. Carga más detalles solo cuando la habilidad se vuelve relevante. Esto significa que puedes instalar muchas habilidades sin consumir constantemente la capacidad del contexto.
Qué Tipos de Comportamiento Puedes Codificar
En realidad, bastante variedad. Las habilidades pueden incluir:
- Instrucciones procedimentales paso a paso — cómo manejar un tipo de archivo particular, patrón de revisión o formato de salida
- Convenciones de dominio — estándares de nomenclatura, reglas específicas de proyectos, librerías preferidas
- Archivos de soporte — plantillas, ejemplos de salida, scripts en Python que Claude puede ejecutar
- Subdocumentos condicionales — archivos de referencia más profundos que solo se cargan cuando Claude determina que son relevantes
Las habilidades preparan a Claude para resolver un problema, en lugar de resolverlo directamente. Esto es fundamentalmente diferente de las herramientas tradicionales, que ejecutan y devuelven resultados.
Esa distinción me pareció importante. Una habilidad no se ejecuta. Da instrucciones. Claude aún hace el razonamiento.
Configuración y uso de las habilidades de Claude
Ubicación y formato de los archivos
Para uso personal en todos los proyectos, las habilidades se colocan en claude skills. Para habilidades a nivel de proyecto compartidas a través de Git, la ruta es claude skills. Cada habilidad necesita su propio subdirectorio y, dentro de este, un archivo SKILL.md.
El formato en sí es sencillo. Las habilidades son fáciles de crear: solo una carpeta con un archivo SKILL.md que contenga frontmatter YAML e instrucciones. El repositorio oficial de habilidades de Anthropic en GitHub incluye una habilidad plantilla que puedes usar como punto de partida, junto con las habilidades de creación de documentos de código abierto que permiten que Claude maneje de manera incorporada PDFs, Word y PowerPoint.
Cómo Claude lee y aplica las instrucciones de las habilidades
Una vez que se instala una habilidad, Claude monitorea las tareas entrantes y las compara con las descripciones de las habilidades. Cuando hay una coincidencia, carga el contenido del SKILL.md en el contexto y sigue las instrucciones desde allí.
También puedes invocar habilidades manualmente con un comando de barra — skill-name — o dejar que Claude decida automáticamente en función del contexto de la tarea. Ambos modos funcionan de la misma manera internamente.
Noté algo interesante aquí: cuando Claude usa una habilidad, no solo "conoce" las instrucciones. Las lee de nuevo cada vez, como si consultara un documento. Esto tiene implicaciones a las que volveré más adelante.
Dónde funcionan bien las habilidades de Claude
Conocimiento del dominio y convenciones del proyecto
Probablemente aquí es donde las habilidades destacan más claramente. Si tu equipo tiene estándares de codificación particulares, un flujo de depuración preferido o requisitos de salida específicos, codificarlos en un archivo de habilidad significa que Claude los aplica de manera consistente, sin que tengas que repetir el contexto en cada sesión.
Probé esto varias veces en diferentes proyectos. La consistencia fue notablemente mejor que solo confiar en las instrucciones de CLAUDE.md o repetirme en los prompts. Claude lee la habilidad, la sigue y el resultado se siente más predecible.
Formato de salida consistente
Para salidas estructuradas: documentos técnicos, revisiones de código, documentación de API — las habilidades funcionan bien como contratos de formato. Describes la estructura esperada, Claude la carga y el resultado coincide de manera más confiable.
Las habilidades de Claude Code siguen el estándar abierto de habilidades de agentes, que funciona en múltiples herramientas de IA. Claude Code amplía el estándar con características adicionales como control de invocación, ejecución de subagentes e inyección dinámica de contexto.
Vale la pena destacar esa compatibilidad multiplataforma. Si estás construyendo en varias herramientas de agentes, se aplica el mismo formato SKILL.md.
Dónde las habilidades de Claude alcanzan un límite
Aquí es donde comencé a notar algo que se sentía un poco diferente de lo que había asumido al principio.
Archivos estáticos vs aprendizaje dinámico
Un archivo SKILL.md es escrito por un humano y guardado en disco. No se actualiza solo. Si Claude realiza una tarea bien usando una habilidad, ese éxito no se retroalimenta en el archivo de la habilidad. La siguiente sesión comienza desde el mismo documento estático.
Puedes pedirle a Claude que capture sus enfoques exitosos y errores comunes en la habilidad, pero es un paso manual. Tú lo inicias. Claude no lo hace por sí mismo.
No estoy seguro de que eso sea un fallo. Es más bien un límite de diseño.
No hay bucle de retroalimentación de ejecución
Cuando Claude aplica una habilidad y produce un resultado, no hay señal que fluya de vuelta a la habilidad misma. No hay registro de qué instrucción funcionó, cuál fue ignorada o cuál causó un problema. La habilidad no tiene memoria de haber sido usada.
Esto importa más cuanto más tiempo se ejecutan agentes en producción. Los patrones se acumulan en tu cabeza, no en el archivo.
Las habilidades no persisten entre agentes o equipos
Las habilidades personalizadas son individuales para cada usuario; no se comparten a nivel organizacional y no pueden ser gestionadas centralmente por administradores.
Así que si una persona en un equipo refina una habilidad basada en meses de uso, esa versión mejorada no se propaga automáticamente a los compañeros de equipo. Permanece local. Alguien tiene que copiarla, comprometerla, compartirla y todos tienen que actualizarla.
No hay nada roto en esto. Pero significa que las mejoras de habilidades viajan lentamente y la red de agentes que usan la habilidad no converge naturalmente hacia un mejor comportamiento con el tiempo.
De habilidades estáticas a capacidad heredable
Qué significa una capacidad reutilizable y validada más allá de SKILL.md
He estado pensando en cómo sería si la ejecución exitosa de una habilidad — por ejemplo, la ejecución exitosa de un agente a través de una secuencia compleja de depuración — pudiera convertirse en algo que otros agentes pudieran heredar directamente. No un archivo copiado, sino una solución verificada con un historial de auditoría.
Las habilidades tal como existen hoy en día se parecen más a documentos de incorporación. Se escriben una vez, basándose en la mejor comprensión actual de alguien, y se distribuyen manualmente. Ese modelo funciona, y funciona bien para dominios estables y bien comprendidos.
Pero para equipos que ejecutan agentes en producción — agentes que fallan, se recuperan, se adaptan — la brecha entre "lo que dice la habilidad" y "lo que realmente funcionó la semana pasada" puede ampliarse silenciosamente.
Cuando necesitas algo que evoluciona
Cuanto más observo los sistemas de agentes en uso real, más noto que la parte difícil no es codificar el conocimiento una vez. Es mantenerlo actualizado. Las habilidades resuelven el problema de la codificación. El problema de la actualidad sigue abierto.
Están surgiendo enfoques a nivel de infraestructura que tratan los comportamientos validados de los agentes como activos compartibles — no archivos estáticos, sino soluciones verificadas con linaje. Esa es una arquitectura diferente a SKILL.md, y plantea diferentes preguntas sobre la confianza y lo que realmente significa "reutilizar" cuando hay agentes involucrados.
Todavía no entiendo completamente dónde se encuentra esa línea.
Límites y compensaciones
Para ser claro sobre lo que he observado:
Las habilidades de Claude son genuinamente útiles. Reducen la repetición, mejoran la consistencia y hacen que la experiencia en un dominio sea portátil entre sesiones. Para desarrolladores individuales y pequeños equipos, representan una mejora significativa sobre el uso de indicaciones ad hoc.
El límite aparece cuando deseas una capacidad que se mejore a sí misma, que se transfiera automáticamente entre agentes o que acumule evidencia de ejecuciones reales. Eso no es lo que SKILL.md fue diseñado para hacer.
El compromiso es simple: previsibilidad vs. adaptabilidad. Las habilidades te dan previsibilidad. No te dan —por diseño— un agente que aprenda de su propia historia.
Preguntas frecuentes
- ¿Qué es un archivo SKILL.md en Claude Code?
Un archivo SKILL.md es el componente central de una habilidad de Claude: un documento Markdown con frontmatter YAML que proporciona a Claude instrucciones específicas del dominio, contexto y metadatos. Indica a Claude cuándo aplicar la habilidad y qué hacer cuando lo hace. Las habilidades aprovechan el entorno VM de Claude para ofrecer capacidades más allá de lo posible solo con indicaciones.
- ¿Cómo funcionan las habilidades de Claude?
Claude lee los metadatos de la habilidad al iniciar y carga las instrucciones completas solo cuando se detecta una tarea relevante o cuando invocas la habilidad manualmente con un comando de barra. Esta carga progresiva mantiene bajo el uso de contexto. Los archivos de soporte dentro del directorio de la habilidad se cargan bajo demanda según las necesidades de Claude.
- ¿Cómo creo una habilidad personalizada para Claude Code?
Crea un directorio bajo .claude/skills/ en tu proyecto (o ~/.claude/skills/ para uso personal). Añade un archivo SKILL.md con el frontmatter YAML que contenga nombre y descripción, seguido de tus instrucciones de marcado. Claude descubrirá y aplicará la habilidad automáticamente cuando sea relevante. Puedes consultar el repositorio de Anthropic skills en GitHub para plantillas y ejemplos, o leer la documentación completa de Habilidades de Agente para orientación de configuración. Para un desglose técnico más profundo, la entrada del blog de ingeniería de Anthropic sobre Habilidades de Agente merece la pena leerla detenidamente. Si usas el SDK, Habilidades de Agente en el SDK explica cómo funcionan el descubrimiento de habilidades y el acceso a herramientas en ese contexto.
- ¿Son las habilidades de Claude las mismas que las de MCP?
No exactamente — aunque a veces me encuentro confundiendo ambas cosas. Las herramientas MCP (Model Context Protocol) son capacidades externas que Claude llama en tiempo de ejecución: sistemas de archivos, bases de datos, APIs, servicios. Se ejecutan y devolven resultados. Las habilidades de Claude, en cambio, son instructivas — le dicen cómo comportarse o abordar una tarea, en lugar de darle una nueva herramienta para llamar. Una habilidad puede guiar a Claude en un proceso de revisión de código; una herramienta MCP podría realmente recuperar el archivo que se está revisando. Pueden trabajar conjuntamente, pero están resolviendo problemas diferentes. Una le da acceso a Claude; la otra le da orientación a Claude.
- ¿Se pueden compartir las habilidades de Claude entre proyectos?
Parcialmente. Las habilidades que se colocan en ~/.claude/skills/ son personales y se aplican a todos tus proyectos en esa máquina. Las habilidades colocadas en .claude/skills/ dentro de un directorio de proyecto están asignadas por alcance de proyecto y pueden comprometerse en Git — lo que significa que los compañeros que clonan el repositorio obtienen automáticamente las mismas habilidades. Lo que no ocurre es ningún tipo de sincronización o propagación automática más allá de eso. Si refinas una habilidad en un proyecto, esa mejora no fluye por sí sola. El compartir es manual: copiar, enviar, distribuir. Para individuos y equipos pequeños que trabajan en el mismo repositorio, esto funciona razonablemente bien. Para organizaciones grandes que ejecutan flujos de trabajo de múltiples agentes en diferentes entornos, la fricción empieza a notarse.
*Seguiré observando cómo evoluciona este espacio. La brecha entre instrucciones estáticas y la capacidad de agente autoactualizable parece reducirse — lentamente, y no siempre de forma evidente. Todavía no sé qué pensar. *Nos vemos la próxima vez.
