Un archivo SKILL.md es el corazón de cada Claude Skill: un archivo Markdown que comienza con un breve encabezado YAML (un name y una description) y continúa con las instrucciones que Claude debe seguir. La descripción le indica a Claude cuándo usar el Skill; el cuerpo le indica cómo hacerlo.
Si has visto el term y te has preguntado qué contiene realmente, aquí tienes la anatomía de un SKILL.md, por qué importa cada parte 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. Está escrito en Markdown simple, por lo que se abre en cualquier editor de texto. Claude lo lee para aprender una capacidad: los pasos, las reglas y las prácticas recomendadas para un tipo de tarea. Los elementos adicionales opcionales (plantillas, scripts y archivos de referencia) pueden estar junto a él en la misma carpeta, pero SKILL.md es el único archivo que todo Skill debe tener.
¿Quieres ver un SKILL.md bien delimitado en lugar de crear uno desde cero? Los metadatos iniciales y las instrucciones de Yuri ya están redactados y probados para detectar errores, vulnerabilidades de seguridad y problemas de rendimiento durante una revisión.
Ver Yuri - Skill de AI para revisión de código →Las dos partes de un SKILL.md
1. Los metadatos iniciales
En la parte superior hay un pequeño bloque YAML entre marcadores ---. Contiene los metadatos esenciales - como mínimo, un name y una description:
---
name: weekly-report
description: Da formato a notas sin procesar para convertirlas en nuestro informe semanal estándar. Úsalo cuando el usuario pida una actualización semanal, un informe de estado o que «redactes el resumen de la semana».
---Este bloque es especial: cuando comienza una sesión, Claude precarga únicamente el nombre y la descripción de cada Skill instalada, no el archivo completo. Esto mantiene ligero el contexto y es la razón por la que la descripción hace tanto trabajo.
2. El cuerpo (instrucciones)
Debajo de los metadatos iniciales, en Markdown normal, escribes lo que Claude debería hacer realmente - idealmente como pasos numerados y claros, con cualquier regla o ejemplo:
## Pasos
1. Agrupa las notas bajo «Logros», «En curso» y «Bloqueos».
2. Mantén cada viñeta en una sola frase y en pasado.
3. Termina con un resumen de una línea titulado «La próxima semana».
4. Nunca inventes métricas que no aparezcan en las notas.Por qué la descripción es la línea más importante
La activación 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 («úsala cuando el usuario pida una actualización semanal o un informe de estado») se activa de forma fiable. Si recuerdas una sola regla, que sea esta: escribe la descripción indicando cuándo usar la skill, no solo qué es.
Cómo usa Claude el archivo
- Al iniciarse: 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). - Después: Claude sigue las instrucciones del cuerpo para completar el trabajo.
Este enfoque de «cargarla solo cuando sea necesario» se llama divulgación progresiva y permite mantener muchas skills instaladas sin sobrecargar el contexto del modelo.
Cómo escribir un buen SKILL.md
- Perfecciona la descripción. Indica claramente cuándo debe activarse la skill.
- Mantén pequeña la primera versión. Cinco a diez líneas de pasos claros son mejores que un documento interminable.
- Sé concreto. Incluye pasos numerados, reglas explícitas y un ejemplo breve.
- Prueba con tareas reales. Amplíala solo donde Claude falle.
¿Tienes que escribir una tú mismo?
No. Escribir la tuya es ideal para flujos de trabajo únicos para ti, pero si solo quieres el resultado, las skills prediseñadas ya incluyen su SKILL.md redactado y probado. Explora la biblioteca de KissMySkills con más de 1.000 skills, paquetes de prompts y agentes, o la colección de skills de Claude Code. ¿Quieres ver una en acción primero? Prueba un generador gratuito o consigue una skill gratuita.
No todos los archivos SKILL.md son para programadores: los metadatos iniciales y las instrucciones de Ryan están redactados para presentaciones para la junta directiva, memorandos para toda la empresa y resúmenes ejecutivos, sin necesidad de edición.
Ver el Skill de AI de Ryan - Jefe de gabinete →Preguntas frecuentes
¿SKILL.md es simplemente Markdown?
Sí: es un archivo Markdown estándar con un bloque de metadatos iniciales en YAML en la parte superior. Se abre en cualquier editor de texto; no se necesita ningún software especial.
¿Qué se necesita en un SKILL.md?
Como mínimo, un bloque de metadatos iniciales con un nombre y una descripción. El cuerpo con las instrucciones es lo que hace útil al Skill, pero los metadatos son lo que permite descubrirlo y activarlo.
¿Dónde va el archivo SKILL.md?
En la raíz de la carpeta del Skill. En Claude Code, los Skills se encuentran ~/.claude/skills/<name>/ para uso personal o .claude/skills/<name>/ dentro de un proyecto, en 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 portátiles: pega el cuerpo en las instrucciones personalizadas de ChatGPT o Gemini para obtener el mismo comportamiento. La activación automática mediante los metadatos iniciales es una función de Claude.
En resumen:
Si prefieres no escribir tú mismo los metadatos iniciales en YAML, Yuri - Revisor de código es una opción sólida para desarrolladores, y Ryan - Jefe de gabinete se ocupa de la redacción ejecutiva y empresarial. Todos funcionan en Claude, ChatGPT y cualquier chat con AI, sin necesidad de programar y con una garantía de devolución del dinero de 30 días.
Empieza con un ejemplo funcional
La forma más rápida de entender SKILL.md es leer uno bueno. Consigue un Skill gratuito, abre el archivo y observa la estructura de metadatos iniciales más pasos en acción; después lee cómo instalarlo en tres minutos.