Antes de los temas, una vista general. Un SKILL.md de producción no es un muro de texto: es un documento con secciones con nombre, cada una respondiendo una pregunta de Claude al ejecutarla. El diagrama de abajo muestra la estructura principal del archivo que vamos a analizar.
La columna vertebral del SKILL.md: ilustrativa. Cada sección alimenta la página final.
Contenido detallado
🗺️ La promesa: "What This Skill Does"
La primera sección de contenido del archivo es un solo párrafo, pero es el párrafo más importante. Él define la salida de forma concreta: "una página HTML interactiva y autónoma, con tema claro/oscuro, rutas de vuelo animadas, agenda día a día, tarjetas de vuelo expandibles, listas de verificación persistentes en localStorage y navegación multiviaje". Y termina con la frase que resume toda la filosofía: "parece una app de viajes premium, no un documento".
🎯 El contrato en una frase
Toda skill madura empieza diciendo sin rodeos qué va a entregar. Ese párrafo es un contrato de tres niveles:
- •Forma de salida: un archivo HTML, no un PDF ni una respuesta en texto.
- •Funciones: la lista de recursos se convierte en una checklist implícita que Claude intenta cumplir.
- •Sensación: "app premium, no documento" es el criterio de calidad.
Fragmento real del SKILL.md
## What This Skill Does
Generates a stunning, interactive HTML travel
itinerary — a single self-contained file with
dark/light theme toggle, animated flight paths,
interactive day-by-day schedule, expandable
flight cards ... and multi-trip navigation.
The output looks like a premium travel app —
not a document.
💡 Consejo práctico
Cuando escribas tu skill, oblígate a describir la salida en una frase verificable. Si tú no puedes, Claude tampoco podrá. "Genera algo útil sobre viajes" es una mala indicación; "genera un HTML interactivo con agenda, vuelos y presupuesto" define un objetivo.
💬 El Setup Flow conversacional
Aquí está el corazón de la skill, y se encarga de dejarlo claro: "Setup Flow — CRITICAL". Antes de generar CUALQUIER cosa, Claude debe seguir un proceso de descubrimiento conversacional de cuatro pasos. Esa es la razón por la que el resultado parece mágico: se construye a partir de datos reales de la vida del usuario, no de suposiciones.
Detalles básicos del viaje
Las preguntas clave
Adónde va, en qué fechas, desde dónde sale, si es para un evento específico y quién viaja. Cinco preguntas que delimitan el resto de la conversación.
Verificación de integraciones
"preguntar cada vez"
Ofrecer obtener datos reales de correo electrónico, calendario, Drive, mensajes y URLs. Lo detallamos en el Tema 3: es lo que distingue a un asistente de un generador de texto.
Detalles profundos (brechas)
Completar lo que falta
Con base en lo que ya recopilaste, preguntar sobre vuelos, alojamiento, eventos, transporte, mascotas, presupuesto, actividades y requisitos especiales: solo lo que esté en blanco.
Confirmar y generar
La puerta antes del resultado
Mostrar un resumen de todo lo recopilado y confirmar antes de construir. Solo entonces se genera la página HTML.
📊 Por qué «recopilar antes de generar» funciona
- Especificidad: los datos reales producen una página que parece hecha para ese viaje, no una plantilla.
- Confianza: al confirmar el resumen, el usuario corrige errores antes de gastar tokens generando todo el HTML.
- Orden: los pasos van desde lo más barato (preguntas) hasta lo más caro (generar), reduciendo el retrabajo.
🔌 Integraciones vía MCP: datos reales
El Paso 2 de la configuración es donde la skill obtiene superpoderes. Le indica a Claude que ofrezca — cada vez — revisar las fuentes de datos del usuario: correo electrónico, calendario, Drive/Docs, Slack/mensajes, URLs y Notion. Si el usuario autoriza, Claude usa las herramientas MCP correspondientes (Gmail, Google Calendar, Google Drive) para traer confirmaciones de vuelos, reservas y entradas a eventos directamente al documento.
✓ Qué HACER
- ✓Ofrecer la integración y esperar la autorización del usuario.
- ✓Usar la herramienta MCP adecuada para cada fuente (Gmail para correo electrónico, Calendar para agenda).
- ✓Completar el documento con los datos reales que vuelvan.
- ✓Volver a las preguntas (Paso 3) para lo que la integración no cubrió.
✗ Qué NO hacer
- ✗Acceder al correo electrónico o al calendario sin preguntar.
- ✗Inventar números de vuelo o reservas cuando no hay datos.
- ✗Omitir la oferta porque «debe dar trabajo» — la skill dice «ask every time».
- ✗Mezclar datos de marcador de posición con datos reales sin etiquetarlos.
Las fuentes que la skill ofrece verificar
💡 Consejo práctico
La frase de la skill, "I can pull in real data to make this way more useful", es un modelo de copy. Explica el beneficio antes de pedir permiso: el usuario entiende por qué y tiende a decir que sí. Copia este patrón en tus skills con integración.
📦 Output Format: un archivo, cero dependencias
Muy breve, pero decisiva. La sección "Output Format" define la salida con reglas explícitas: un único HTML autónomo, con todo el CSS en un <style> y todo el JS en un <script>; imágenes como data URIs base64 o emoji; ninguna dependencia externa aparte de Google Fonts (Inter); y un nombre de archivo estandarizado.
Fragmento real del SKILL.md
## Output Format
Generate a single self-contained HTML file.
All CSS inline in <style>. All JS inline in
<script>. Images as base64 data URIs or emoji
fallbacks. No external dependencies except
Google Fonts (Inter).
Save as travelwings-{destination}.html
📊 Lo que evita cada restricción
- "Single file": evita archivos dispersos que el usuario tiene que juntar.
- "Inline CSS/JS": evita enlaces a hojas/scripts que se rompen al mover el archivo.
- "base64 / emoji": evita imágenes que no cargan sin conexión.
- "No external deps": evita dependencias de CDN que desaparecen con el tiempo.
⚠️ Atención
Sin una sección de Output Format, Claude tiende a «ayudar demasiado»: propone un proyecto con varias carpetas, un framework y un build. Para una skill que genera un artefacto para el usuario final, eso es lo opuesto a lo que se busca. Restringir es diseñar.
🧩 Secciones de ejemplo: el plano de la página
Esta sección enumera 13 bloques sugeridos para la página —hero, banner de evento, estadísticas, mapa de ruta, vuelos de ida, hotel, mascotas, agenda día a día, vuelos de vuelta, presupuesto, listas de verificación, pie de página y tema. Pero el detalle importante está entre paréntesis: "adaptar según cada viaje". Es un plano, no una camisa de fuerza.
✓ Cómo ayuda la lista
- ✓Le da a Claude una orden de referencia de los bloques.
- ✓Recuerda las secciones que es fácil olvidar (pie de página, listas de verificación).
- ✓Marca cuáles son condicionales ("si asistes a un evento", "si corresponde").
✗ Qué evitar
- ✗Volcar todos los 13 bloques incluso sin datos para ellos.
- ✗Crear una sección de mascotas en un viaje sin mascotas.
- ✗Tratar el orden sugerido como obligatorio y estricto.
Los 13 bloques sugeridos (adaptar según el viaje)
💡 Consejo práctico
"Adapt per trip" es una de las dos palabras más poderosas en una skill de generación. Siempre que enumeres bloques, marca cuáles son condicional. Así das estructura sin crear páginas infladas con secciones vacías.
⭐ Key Principles: la brújula
La sección final consta de seis principios breves que resumen el espíritu de la skill. Mientras que los pasos indican qué hacer, los principios dicen cómo decidir cuando la situación no estaba en el guion. Son la regla práctica de Claude.
🧭 Los seis principios
- 1.Datos reales > datos de marcador de posición. Intentar siempre partir primero de los datos reales.
- 2.Ask before assuming. La conversación de configuración es lo que aporta valor.
- 3.One file, zero dependencies. Todo autosuficiente.
- 4.Parece una aplicación prémium, no un documento. El estándar de calidad.
- 5.Interactive > static. Las listas de verificación guardan el estado, los días se pueden marcar y los vuelos se expanden.
- 6.Colour-code everything. Azul de ida, verde confirmado, naranja de vuelta, lavanda para conexión, dorado para evento.
📊 Pasos vs. principios
- Pasos cubren el camino ideal: haz A, luego B y después C.
- Principios cubren los imprevistos: ¿qué pasa si falta un dato? ¿Y si hay un conflicto? Decide según los criterios.
- Juntos, hacen que la skill robusta — funciona incluso fuera del flujo previsto.
💡 Consejo práctico
Los buenos principios son cortos y refutables: cada uno descarta una alternativa concreta ("real > placeholder" descarta inventar datos). Si un principio tuyo no excluye nada, es solo decoración: reescríbelo.
Ejercicios prácticos
1. Mapea las secciones
Abre cualquier skill que genere un artefacto e identifica: ¿dónde está la promesa? ¿Hay un setup flow? ¿Hay una sección de Output Format? ¿Hay principios? Anota lo que falta.
2. Escribe la promesa
Describe en una frase verificable el resultado de una skill que te gustaría tener. Pon la frase a prueba: ¿se puede comprobar si el resultado cumple?
3. Crea un SKILL.md ejecutable
Guarda el archivo de abajo como ~/.claude/skills/menu-planner/SKILL.md, reinicia Claude Code y escribe /menu. Observa cómo la skill guía su propio setup flow.
---
name: menu-planner
description: Generates a self-contained HTML weekly
meal plan. Trigger on "/menu", "plan my meals",
"weekly menu", "meal prep". Asks about diet,
people, budget and pantry BEFORE generating.
---
# Menu Planner
## What This Skill Does
Generates a single self-contained HTML weekly meal
plan: 7 day cards, a shopping list grouped by aisle,
a budget total, and a print button. Looks like an
app, not a document.
## Setup Flow — CRITICAL
Before generating, ask:
1. How many people, and any diets/allergies?
2. Budget for the week?
3. What's already in the pantry? (offer to read a
note/doc if they have one)
4. Confirm a summary, THEN generate.
## Output Format
One HTML file. CSS in <style>, JS in <script>.
No external deps except Google Fonts (Inter).
Save as menu-{week}.html.
## Key Principles
1. Ask before assuming.
2. One file, zero dependencies.
3. Interactive > static (check off items, save state).
4. Colour-code by meal type.
🎯 Resumen del módulo
Siguiente Módulo:
2.2 — Flujo de configuración, sistema de diseño y resultado: del prompt a la página HTML