Un archivo SKILL.md es el corazón de cada Claude Skill: un archivo Markdown que comienza con un pequeño encabezado YAML (un nombre y una descripción) y seguido por las instrucciones que Claude debe seguir. La descripción es lo que indica a Claude cuándo usar la skill; el cuerpo le dice cómo hacerlo.
Si has visto el término y te has preguntado qué contiene realmente, aquí tienes la anatomía de un SKILL.md, por qué cada parte es importante y cómo escribir uno que funcione.
Qué es SKILL.md
Un Claude Skill es una carpeta, y SKILL.md es el archivo obligatorio en su raíz. Es Markdown simple, por lo que se abre en cualquier editor de texto. Claude lo lee para aprender una capacidad: los pasos, reglas y mejores prácticas para un tipo de tarea. Extras opcionales (plantillas, scripts, archivos de referencia) pueden estar junto a él en la misma carpeta, pero el SKILL.md es el único archivo que toda skill debe tener.
Las dos partes de un SKILL.md
1. El frontmatter (metadatos)
En la parte superior hay un pequeño bloque YAML entre marcadores ---. Contiene los metadatos esenciales — como mínimo un nombre y una descripción:
---
name: weekly-report
description: Formatea notas en bruto en nuestro informe semanal estándar. Usar cuando el usuario pida una actualización semanal, informe de estado o "resumen de la semana."
---Este bloque es especial: cuando inicia una sesión, Claude precarga solo el nombre y la descripción de cada skill instalada — no el archivo completo. Esto mantiene ligera la ventana de contexto y es por eso que la descripción tiene tanta importancia.
2. El cuerpo (instrucciones)
Debajo del frontmatter, en Markdown normal, escribes lo que Claude debe hacer realmente — idealmente como pasos claros y numerados con reglas o ejemplos:
## Pasos
1. Agrupa las notas bajo Ganancias, En Progreso y Bloqueos.
2. Mantén cada viñeta en una oración, en pasado.
3. Termina con un resumen de una línea "La próxima semana".
4. Nunca inventes métricas que no estén en las notas.Por qué la descripción es la línea más importante
El disparo depende completamente de la descripción. Mientras trabajas, Claude compara tu solicitud con la descripción de cada skill y carga el archivo completo solo cuando coincide. Una descripción vaga ("ayuda con informes") rara vez se activa. Una específica ("usar cuando el usuario pida una actualización semanal o informe de estado") se activa de forma confiable. Si recuerdas una regla, que sea esta: escribe la descripción para cuándo usar la skill, no solo qué es.
Cómo Claude usa el archivo
- Al iniciar: Claude lee el nombre y la descripción de cada skill.
-
Durante la tarea: si tu solicitud coincide con una descripción, Claude carga el
SKILL.mdcompleto de esa skill (y cualquier recurso adjunto). - Luego: Claude sigue las instrucciones del cuerpo para completar el trabajo.
Este enfoque de "cargar solo cuando es necesario" se llama divulgación progresiva, y es lo que permite tener muchas skills instaladas sin sobrecargar el contexto del modelo.
Cómo escribir un buen SKILL.md
- Clava la descripción. Indica claramente cuándo debe activarse la skill.
- Mantén la primera versión pequeña. Cinco a diez líneas de pasos claros superan a un documento extenso.
- Sé concreto. Pasos numerados, reglas explícitas, un ejemplo corto.
- Prueba con tareas reales. Amplía solo donde Claude falle.
¿Tienes que escribir uno tú mismo?
No. Escribir el tuyo es ideal para flujos de trabajo únicos, pero si solo quieres el resultado, las skills ya hechas vienen con su SKILL.md creado y probado. Explora la biblioteca KissMySkills con más de 300 skills, paquetes de prompt y agentes, o la colección de Claude Code skills. ¿Quieres ver uno en acción primero? Prueba un generador gratuito o descarga una skill gratuita.
Preguntas frecuentes
¿SKILL.md es solo Markdown?
Sí — es un archivo Markdown estándar con un bloque frontmatter YAML en la parte superior. Se abre en cualquier editor de texto, sin software especial.
¿Qué se requiere en un SKILL.md?
Como mínimo, un bloque frontmatter con un nombre y una descripción. El cuerpo con instrucciones es lo que hace útil la skill, pero los metadatos son lo que la hace descubrible y activable.
¿Dónde va el archivo SKILL.md?
En la raíz de la carpeta de la skill. En Claude Code, las skills viven en ~/.claude/skills/<nombre>/ para uso personal o .claude/skills/<nombre>/ dentro de un proyecto, con el SKILL.md en la raíz de la carpeta.
¿Puedo usar el contenido de un SKILL.md en ChatGPT o Gemini?
Sí. Las instrucciones son portables: pega el cuerpo en las instrucciones personalizadas de ChatGPT o Gemini para el mismo comportamiento. La activación automática vía frontmatter es una función de Claude.
Comienza con un ejemplo funcional
La forma más rápida de entender SKILL.md es leer uno bueno. Descarga una skill gratuita, abre el archivo y observa la estructura de frontmatter más pasos en acción — luego lee cómo instalarla en tres minutos.