Un archivo SKILL.md es el corazón de toda Skill de Claude: un archivo Markdown que comienza con un encabezado YAML breve (un name y una description) y al que siguen las instrucciones que Claude debe seguir. La descripción indica a Claude cuándo usar la Skill; el cuerpo le indica 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é es importante cada parte y cómo escribir uno que funcione.
Qué es SKILL.md
Una Skill de Claude es una carpeta, y SKILL.md es el archivo obligatorio en su raíz. Es Markdown sin formato especial, 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 colocarse junto a él en la misma carpeta, pero el SKILL.md es el único archivo que toda 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 escritos y probados para detectar errores, fallos de seguridad y problemas de rendimiento durante una revisión.
Ver Yuri - Skill de IA de revisión de código →Las dos partes de un SKILL.md
1. Los metadatos iniciales (metadatos)
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 todo el archivo. Esto mantiene ligero el contexto y por eso la descripción tiene tanta importancia.
2. El cuerpo (instrucciones)
Debajo de los metadatos iniciales, en Markdown normal, escribes lo que Claude debe hacer realmente - idealmente como pasos claros y numerados, con las reglas o ejemplos pertinentes:
## Pasos
1. Agrupa las notas en Logros, En curso y Bloqueos.
2. Mantén cada viñeta en una sola oración y en pasado.
3. Termina con un resumen de una línea titulado «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
La activación depende por completo 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 pensando en cuándo usar la skill, no solo en 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 «cargarlo solo cuando sea necesario» se llama divulgación progresiva y es lo que te 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. Pasos numerados, reglas explícitas y un ejemplo breve.
- Prueba con tareas reales. Amplía solo donde Claude falle.
¿Tienes que escribir una tú mismo?
No. Escribir el tuyo es ideal para flujos de trabajo únicos para ti, pero si solo quieres el resultado, las skills prediseñadas ya incluyen su SKILL.md creado 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 primero en acción? Prueba un generador gratuito o consigue una skill gratuita.
No todos los SKILL.md son para programadores - los metadatos iniciales y las instrucciones de Ryan están redactados para dosieres de junta directiva, memorandos para toda la empresa y resúmenes ejecutivos, sin necesidad de edición.
Ver el AI Skill de Ryan - Jefe de personal →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 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 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 personal se ocupa de la redacción ejecutiva y empresarial. Todos funcionan en Claude, ChatGPT y cualquier chat de 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. Descarga un Skill gratuito, abre el archivo y observa en acción la estructura de metadatos iniciales más pasos - después lee cómo instalarlo en tres minutos.
