Documentación de Habilidades de Claude Code: La Referencia Completa para Desarrolladores

No planeaba profundizar en esto hoy. Solo estaba tratando de entender por qué la configuración de Claude Code de un colega se comportaba tan diferente de la mía, y la respuesta resultó estar en una carpeta que apenas había notado.

Qué Cubre la Documentación de Habilidades de Claude Code

La frase "documentación de habilidades de Claude code de Anthropic" aparece en muchas búsquedas de desarrolladores, y creo que hay una razón para ello: el sistema de habilidades está genuinamente distribuido en varias superficies diferentes, y puede tomar algún tiempo juntar cómo se conectan.

Este artículo se basa en fuentes oficiales de Anthropic. Pero intenta añadir algo que las docuementaciones por sí solas no pueden ofrecer completamente: una capa más lenta de entendimiento, construida a partir de la observación.

Dónde encontrar la documentación oficial

El punto de partida canónico es Referencia de habilidades de Claude Code de Anthropic, que cubre el ciclo de vida completo de las habilidades, el formato SKILL.md, y cómo Claude descubre y carga habilidades automáticamente.

Para entender cómo encajan las habilidades en el panorama más amplio de los agentes, incluyendo cómo se comparan con Proyectos, MCP y subagentes, Anthropic publicó un blog útil: Habilidades explicadas: Cómo se comparan las habilidades con prompts, Proyectos, MCP y subagentes. Ese artículo me ayudó a entender no solo el qué, sino el cuándo.

Lo que este artículo añade más allá de la documentación oficial

La documentación oficial es precisa y está bien estructurada. Lo que no siempre captura es el patrón de pequeñas sorpresas — los momentos en los que una habilidad no se activa, o se activa de manera demasiado amplia, o donde te das cuenta de que un archivo SKILL.md y un archivo CLAUDE.md estaban haciendo trabajos ligeramente diferentes que habías confundido.

Eso es lo que estoy tratando de trazar aquí.

Referencia de Formato SKILL.md

Ubicación y nombrado de archivos

Cada habilidad necesita un archivo SKILL.md con dos partes: frontmatter YAML (entre los marcadores ---) que le indica a Claude cuándo usar la habilidad, y contenido en markdown con instrucciones que Claude sigue cuando se invoca la habilidad.

En Claude Code, las habilidades viven en .claude/skills/<skill-name>/SKILL.md dentro de un proyecto, o en ~/.claude/skills/<skill-name>/SKILL.md para habilidades globales de usuario. El nombre de la carpeta y el campo name en el frontmatter se convierten en el comando con barra — así que .claude/skills/explain-code/SKILL.md con name: explain-code crea el comando /explain-code.

Las habilidades definidas en .claude/skills/ dentro de directorios añadidos a través de --add-dir se cargan automáticamente y son detectadas por el sistema de cambio en tiempo real, por lo que puedes editarlas durante una sesión sin reiniciar. Ese comportamiento me sorprendió un poco: esperaba necesitar un reinicio.

Tipos de instrucciones admitidas

Las habilidades proporcionan a Claude nuevas capacidades mediante instrucciones y código. En la práctica, el cuerpo en markdown puede contener casi cualquier cosa sobre la que Claude pueda razonar: procedimientos paso a paso, reglas de estilo, plantillas de salida, terminología de dominio, contenido de referencia y ejemplos inline. Se recomienda usar la forma imperativa en las instrucciones.

Un detalle que vale la pena mencionar según la documentación oficial del creador de habilidades: el campo de descripción es el mecanismo principal de activación; incluye tanto lo que la habilidad hace COMO los contextos específicos para cuándo usarla. Toda la información de "cuándo usar" va aquí, no en el cuerpo.

Sintaxis y estructura del formato

El SKILL.md mínimo se ve así:

Plain

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Instructions Claude follows when this skill is active]

Al iniciar, el agente precarga el nombre y la descripción de cada habilidad instalada en su prompt del sistema. Estos metadatos representan el primer nivel de divulgación progresiva: proporcionan solo la información suficiente para que Claude sepa cuándo debe usarse cada habilidad sin cargar todo el contenido en el contexto.

Las habilidades también pueden incluir archivos de soporte — documentación de referencia, scripts, recursos — en subdirectorios. Al mover las instrucciones de rellenado de formularios a un archivo aparte, el autor de la habilidad puede mantener el núcleo de la habilidad ligero, confiando en que Claude leerá ese archivo solo cuando sea necesario.

Límites de caracteres y longitud

No hay un límite estricto de caracteres aplicado al propio SKILL.md. La cantidad de contexto que se puede incorporar en una habilidad es prácticamente ilimitada, porque la divulgación progresiva significa que Claude carga archivos adicionales solo cuando se necesitan. Pero, en la práctica, mantener SKILL.md centrado en instrucciones principales —menos de 500 líneas— minimiza la sobrecarga de contexto. Mueve el contenido detallado a references/ y enlázalo.

Lo que pueden instruir las Habilidades de Claude Code

Preferencias de estilo y formato

Las habilidades son adecuadas para codificar estándares de salida: cómo estructurar un informe, qué tono usar, qué encabezados incluir. Puedes crear una habilidad de guías de marca que incluya la paleta de colores de tu empresa, reglas de tipografía y especificaciones de diseño. Cuando Claude crea presentaciones o documentos, aplica automáticamente estos estándares sin que necesites explicarlos cada vez.

Conocimiento específico de dominio

Probablemente aquí es donde las habilidades son más útiles en el trabajo diario. Cualquier dominio que requiera que Claude sepa algo que no conocería a partir de la formación general —tus convenciones internas de API, un formato de datos propietario, un flujo de trabajo específico de la empresa— puede empaquetarse en una habilidad y reutilizarse sin tener que repetirlo en cada solicitud.

Preferencias de uso de herramientas

Las habilidades pueden especificar qué herramientas preferir, en qué orden y bajo qué condiciones. Cuando Claude invoca una habilidad, el sistema sigue un flujo de trabajo simple: carga SKILL.md, lo expande en instrucciones detalladas, inyecta esas instrucciones como nuevos mensajes de usuario en el contexto de la conversación, modifica el contexto de ejecución (herramientas permitidas, selección de modelo) y continúa la conversación con este entorno enriquecido.

Requisitos de estructura de salida

Puedes definir plantillas de salida muy precisas dentro de una habilidad. El repositorio de GitHub de habilidades de Anthropic tiene múltiples ejemplos que muestran cómo anclar a Claude a formatos exactos —estructuras de informes, patrones de mensajes de commit, disposiciones de archivos de prueba.

Lo que las habilidades no pueden hacer

Ejecutar código

SKILL.md es contenido de instrucciones, no código ejecutable. Indica a Claude cómo abordar una tarea; no ejecuta nada por sí mismo. Los scripts dentro del directorio /scripts de una habilidad pueden ser invocados por Claude durante la ejecución de la tarea, pero SKILL.md en sí solo es texto.

Aprender de los errores

Las habilidades personalizadas no se sincronizan entre superficies. Las habilidades subidas en una superficie no están automáticamente disponibles en otras. Más fundamentalmente, una habilidad no se actualiza en función de lo sucedido en una sesión pasada. Las instrucciones son estáticas hasta que las editas. Me pareció útil recordarlo: una habilidad es una instantánea de experiencia, no un ciclo de aprendizaje.

Compartir automáticamente entre agentes o sesiones

Las habilidades están limitadas a las superficies en las que se instalan. Una habilidad creada en Claude Code no está automáticamente disponible en Claude.ai ni a través de la API a menos que la subas por separado.

Habilidades vs. Prompts del sistema vs. Reglas del proyecto vs. Memoria

Aquí es donde más tiempo pasé confundido. Así es como ahora entiendo las diferencias:

Mecanismo	Qué hace	Alcance	¿Persiste entre sesiones?
SKILL.md	Instrucciones específicas del dominio cargadas bajo demanda	Proyecto o usuario-global	Sí (basado en archivo)
CLAUDE.md	Contexto y convenciones del proyecto siempre cargadas	Nivel de proyecto	Sí (basado en archivo)
Prompt del sistema	Establece el comportamiento base del modelo	Nivel API/SDK	Solo si lo configuras cada vez
Proyectos (claude.ai)	Contexto persistente para un trabajo en curso	Espacio de trabajo de Claude.ai	Sí
Memoria	Recordatorio de preferencias entre conversaciones	Nivel de usuario	Sí, si está habilitado

Las habilidades enseñan a Claude cómo hacer algo. Un Proyecto podría contener todo el contexto sobre el lanzamiento de tu producto, mientras que una habilidad podría enseñar a Claude los estándares de escritura de tu equipo o el proceso de revisión de código.

CLAUDE.md es un archivo especial que Claude lee al inicio de cada conversación. Incluye comandos de Bash, estilo de código y reglas de flujo de trabajo. Esto le da a Claude un contexto persistente que no puede inferir solo del código. La diferencia clave con SKILL.md: CLAUDE.md se carga siempre; las habilidades se cargan cuando son relevantes.

El prompt del sistema de Claude Code ya contiene alrededor de 50 instrucciones individuales. Dependiendo del modelo, eso representa casi un tercio de las instrucciones que tu agente puede seguir de manera confiable — antes de reglas, plugins, habilidades o mensajes del usuario. Ese número me llamó la atención. Cambia la forma de pensar sobre cuánto poner en cada capa.

Preguntas frecuentes

1 ¿Dónde está la documentación oficial de habilidades de Claude Code?

La referencia principal es la documentación de habilidades de Claude Code. Para el estándar más amplio de Habilidades de Agente — incluyendo cómo funcionan las habilidades preconstruidas y personalizadas en Claude.ai y la API — consulta la visión general de Habilidades de Agente en la documentación de Anthropic.

2 ¿Qué formato usa SKILL.md?

SKILL.md es un archivo Markdown con frontmatter YAML. El frontmatter requiere dos campos: name y description, que Claude lee al iniciar la sesión para decidir cuándo cargar la habilidad. El cuerpo en Markdown contiene las instrucciones reales que Claude sigue cuando se invoca la habilidad. Los campos opcionales incluyen context y agent para el control avanzado de la ejecución.

3 ¿Cuánto puede durar un archivo SKILL.md?

No hay un límite estricto impuesto. La divulgación progresiva es el principio de diseño clave que hace que las Habilidades de Agente sean flexibles y escalables: las habilidades permiten que Claude cargue información solo según sea necesario, por lo que la cantidad de contexto que se puede incluir en una habilidad es efectivamente ilimitada. Dicho esto, la mayoría de las recomendaciones prácticas sugieren mantener el archivo SKILL.md principal por debajo de 500 líneas y derivar los detalles a archivos de soporte en references/.

Todavía no estoy completamente seguro de haber mapeado todos los casos límite aquí. El comportamiento de activación de la habilidad — cuándo Claude decide que una habilidad es relevante frente a cuándo no lo es — es más difícil de predecir de lo que sugiere la documentación del formato. Claude tiende a "subactivar" las habilidades — no usarlas cuando serían útiles. Vale la pena tener esto en cuenta al redactar tu campo de descripción.

Seguiré observando cómo se estabiliza esto.

Documentación de Habilidades de Código Claude: La Referencia Completa para Desarrolladores