Agent Mentor Learn
Claude Code Skills: crea tus propios flujos de trabajo con IA · Lección 2 de 6

Lección 2: Anatomía de una Skill: el archivo SKILL.md

Objetivos de aprendizaje:

  • Entender la estructura en dos partes de SKILL.md
  • Conocer los campos obligatorios del frontmatter YAML
  • Aprender a escribir una description que de verdad funcione
  • Ver cómo organizar la sección de instrucciones

Requisitos: << Lección 1 | Siguiente: Lección 3 >>

Cómo se ve un archivo de Skill

Abre cualquier Skill y encontrarás la misma forma:1

Este archivo tiene dos partes:

  1. Frontmatter YAML (todo lo que está entre los marcadores ---): metadatos que le dan a Claude lo básico sobre esta Skill
  2. Instrucciones en Markdown (todo lo que viene después): las indicaciones reales que le dicen a Claude qué hacer

Frontmatter YAML: cómo Claude encuentra tu Skill

El frontmatter es el bloque de arriba del todo envuelto en ---. Le dice a Claude las dos cosas que más importan:2 3

name: el identificador único de la Skill

  • Reglas: letras minúsculas, dígitos y guiones. Sin espacios.
  • Qué hace: el nombre se convierte en el comando, como /task-organizer
  • Consejo: que sea descriptivo, corto y evidente de un vistazo

Buenos nombres:

  • meeting-notes
  • code-review
  • changelog-generator

Malos nombres:

  • my-skill-1 (no dice nada)
  • super_amazing_task_helper (demasiado largo, y los guiones bajos no están permitidos)
  • taskOrganizer (camelCase — tiene que ser minúsculas con guiones)

description: el campo que más importa

Esta única frase decide tres cosas:4

  1. Cuándo Claude carga esta Skill por su cuenta
  2. Qué ven los usuarios en la lista de Skills
  3. Para qué entiende Claude que sirve esta Skill

Por eso merece más cuidado que cualquier otra cosa del archivo:4

"The description is the single most important field in your frontmatter. A bad description means your skill either never triggers or triggers on everything. The formula: What it does + When to use it + Key capabilities."

(La description es el campo más importante del frontmatter: si está mal escrita, tu Skill nunca se activa o se activa con todo. La fórmula: qué hace + cuándo usarla + capacidades clave.)

Una buena description:

Malas descriptions:

Campos opcionales (se ven en la lección 6, no aquí)

  • model: elegir qué modelo usar
  • allowed-tools: restringir qué herramientas puede tocar esta Skill
  • version: un número de versión

Para tu primera Skill, name y description es todo lo que necesitas.3

Instrucciones en Markdown: decirle a Claude cómo hacerlo

Todo lo que sigue al frontmatter está escrito para que Claude lo lea y lo siga.1

Las buenas instrucciones comparten tres rasgos:

1. Secciones claras

Usa encabezados para separar las partes:

2. Pasos concretos

Flojo:

Sólido:

3. Ejemplos

Si el formato de salida importa, muestra uno:

En cuanto Claude tiene un ejemplo, sabe exactamente cómo disponer las cosas. Mostrar gana a describir: una salida de muestra hace más trabajo que tres párrafos sobre formato.

Cómo trabajan juntas las dos partes

El frontmatter es el mecanismo de descubrimiento; las instrucciones son la guía de ejecución.5 6

  1. Escribes /task-organizer, o simplemente dices «ayúdame a ordenar estas tareas»
  2. Claude lee el name y la description del frontmatter y decide si carga esta Skill
  3. Si la carga, Claude lee las instrucciones completas
  4. Claude recorre los pasos tal como están escritos
  5. La salida coincide con el formato que especificaron las instrucciones

Por esto la description tiene que ser buena: es la única evidencia que tiene Claude al decidir si usa esta Skill o no.4

Escribe «ayuda con tareas» y Claude no tendrá idea de qué situaciones la piden. Escribe «ordena una lista de pendientes desordenada en grupos por prioridad y fecha límite» y las palabras «ordenar», «pendientes» y «tareas» en una petición bastan para traerla.

Un ejemplo real: desarmar una Skill de revisión de código

Esta es una Skill que se usa de verdad:

Desglosado:

  • La description del frontmatter: dice qué hace (revisa código) y qué comprueba (convenciones, errores, rendimiento)
  • Las instrucciones se dividen en tres listas de verificación: convenciones, errores, rendimiento, cada una con puntos concretos que mirar
  • El formato de salida es explícito: cada problema debe llevar una ubicación, un problema y una sugerencia

Una Skill escrita así acierta al primer intento.

Resumen

  • SKILL.md tiene dos partes: frontmatter YAML (metadatos) e instrucciones en Markdown (indicaciones)
  • Campos obligatorios del frontmatter: name (minúsculas, guiones, único) y description (lo que impulsa la activación automática)
  • La fórmula de la description: qué hace + cuándo usarla + capacidades clave
  • Tres rasgos de unas buenas instrucciones: secciones claras, pasos concretos, ejemplos resueltos
  • Cómo encajan las partes: el frontmatter permite a Claude encontrar la Skill; las instrucciones le permiten ejecutarla

En la próxima lección empezamos desde cero y escribimos una Skill completa de principio a fin.

>> Lección 3: Práctica: escribir tu primera Skill

Footnotes

  1. Documentación oficial de Claude Code: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩ ↩2

  2. Blog de ingeniería de Anthropic: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩

  3. Centro de ayuda de Anthropic: How to create custom skills — https://support.claude.com/en/articles/12512198-how-to-create-custom-skills ↩ ↩2

  4. Building skills for Claude, en la práctica: frontmatter YAML y pruebas — https://sjramblings.io/building-skills-for-claude-part-2/ ↩ ↩2 ↩3

  5. Documentación de la plataforma de Anthropic: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩

  6. Análisis a fondo de Claude Skills (una mirada desde los primeros principios) — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩

Ejercicios

01

¿Qué está mal en este frontmatter y cómo lo arreglarías?

Nivel 1: Arreglar un frontmatter roto
Criterios de finalización · marcado local
02

Toma la tarea que encontraste en el ejercicio de la lección 1 y escríbele un frontmatter.

Nivel 2: Escribir un frontmatter para tu propio caso
Criterios de finalización · marcado local