🧬 Anatomía de una Skill

Una Agent Skill es, en esencia, un archivo de texto Markdown llamado SKILL.md. Nada de binarios compilados ni instalaciones complejas: es un documento que puedes abrir en un editor de texto y leer de principio a fin. Lo que lo hace especial no es la tecnología, sino el contrato que establece: enseña a Claude a ejecutar una tarea específica y dice cuándo se aplica esa tarea.

---
name: travel-itinerary
description: Generates an interactive HTML travel itinerary.
  Use when the user wants to "plan a trip", "create an itinerary",
  or types /travel.
---

# TravelWings — AI Travel Itinerary Generator

## Setup Flow
Before generating anything, ask the user the trip basics...

## Output Format
Generate a single self-contained HTML file...

O name es el identificador de la skill. Parece el campo más insignificante del archivo, pero es la clave estable por la que se referencia la skill — en comandos, en otras skills, en registros. Un buen name es corto, en kebab-case, y explica de un vistazo qué es la skill.

Si el name es la identidad, la description é o cerebro del descubrimiento. Es la única parte de la skill que Claude lee cuando decide si debe usarla o no. Por eso, no puede ser una simple definición: tiene que decir lo que hace la skill E cuándo debe usarse. Este módulo solo presenta la idea; todo el Módulo 1.3 está dedicado a escribir descriptions precisas.

Debajo del frontmatter viene el cuerpo de la skill — Markdown libre donde escribes el paso a paso de la ejecución. Aquí se decide la calidad del resultado. Un cuerpo bien estructurado suele tener cuatro bloques recurrentes, como vemos en las skills reales que el curso analiza.

Aquí está el detalle que lo cambia todo: Claude no lee el cuerpo de todas las skills todo el tiempo. Imagina 50 skills instaladas, cada una con cientos de líneas: cargar todo en cada mensaje sería impracticable. En su lugar, mantiene un índice ligero: solo el name + a description de cada skill. Es contra este índice que se compara la solicitud del usuario.

travel-itinerary    → "plan a trip, create an itinerary, /travel"
vibe-coding         → "fix CSS/layout live in the browser before editing"
n8n-reviewer        → "review an n8n automation as a senior engineer"
rag-architect       → "design the right RAG before writing code"
...                 → (só name + description, nunca o corpo inteiro)

Descubrir significa reconocer que la skill se aplica; activar es, en la práctica, cargar el cuerpo y empezar a seguir sus instrucciones. Hay dos caminos para que esto ocurra, y entender la diferencia evita mucha confusión.

🧰 Prompts copiables

Usa estos prompts con Claude para fijar en la práctica el contenido del módulo.

Abra um SKILL.md qualquer que você tenha acesso e me explique,
linha a linha: qual é o frontmatter, o que cada campo (name,
description) faz, e onde começa o corpo de instruções.

Aqui está a description da minha skill: "<cole aqui>".
Lendo SÓ essa linha, sem o corpo, você saberia em quais pedidos
de usuário disparar esta skill? Liste 3 pedidos que disparariam
e 3 que NÃO disparariam.

Vou descrever uma tarefa que faço sempre. Me ajude a separar:
(1) qual seria o name e a description (o gatilho), e
(2) o que vai no corpo (workflow, regras, formato de saída).
A tarefa é: <descreva>.

📤 Ejemplo de salida

Uno SKILL.md mínimo, pero completo y válido: exactamente el esqueleto que vas a ampliar en los próximos módulos.

---
name: changelog-writer
description: Writes a clean CHANGELOG entry from a list of git
  commits. Use when the user asks to "write a changelog",
  "summarize these commits", or "prep release notes".
---

# Changelog Writer

## Workflow
1. Ask for the version number and the commit list (or read it).
2. Group commits into: Added, Changed, Fixed, Removed.
3. Rewrite each line in plain, user-facing language.

## Rules
- Never invent changes that aren't in the commits.
- Keep each entry to a single line.

## Output Format
Markdown under a `## [version] - YYYY-MM-DD` header,
one section per group, bullets per change.

✏️ Ejercicios prácticos