La guía de Skills de Anthropic, en español y en simple

Imagínate que Claude es un empleado nuevo brillante pero que olvida todo entre conversaciones. Una skill es una carpeta de instrucciones que le pegas a la pared: cuando vea cierto pedido, abre la carpeta y sigue lo que ahí dice. Así no le tienes que reexplicar tu workflow cada vez.

Por dentro, la carpeta tiene un archivo principal y, opcionalmente, archivos extra. El único obligatorio es SKILL.md — el resto solo si los necesitas:

• SKILL.md — obligatorio. Las instrucciones en Markdown con frontmatter YAML arriba.
• scripts/ — opcional. Código ejecutable (Python, Bash) para validaciones críticas que no quieres confiarle al modelo.
• references/ — opcional. Documentación detallada que Claude carga solo cuando la necesita. Aquí va lo largo.
• assets/ — opcional. Plantillas, fuentes, íconos que la skill puede usar en el output.

Claude no carga toda tu skill al inicio de cada conversación — sería lentísimo si tuvieras 30 skills prendidas. Las lee en tres niveles, abriendo solo lo que necesita. Por eso la description del frontmatter es la parte más crítica: es lo único que siempre está cargado.

Esta arquitectura es la que hace viable que tengas decenas de skills sin que el contexto se infle. Cuando tu skill se sienta lenta, el primer reflejo es mover detalle del SKILL.md al folder references/ — Claude solo lo cargará si esa parte aplica.

Esta es la parte que le interesa a casi todo mundo: ya tienes una skill (la armaste tú, te la pasaron, la bajaste de un repo) — ¿cómo la prendes? Dos rutas: Claude.ai (web) y Claude Code (CLI). En la web es upload de un .zip; en Claude Code es solo poner la carpeta en el path correcto.

En Claude.ai · Settings → Capabilities → Skills

1. 01

   Abre Settings en Claude.ai

   En la web de Claude (claude.ai), pica tu avatar en la esquina y entra a Settings. Si entras directo, el link de abajo te ahorra dos clics.

   Abrir Settings → Capabilities →
2. 02

   Capabilities → Skills

   En el menú lateral, pica Capabilities. Adentro hay una sección Skills. Si no la ves, asegúrate de que tu cuenta tiene el feature habilitado (en planes Pro y superiores está prendido por default desde finales de 2025).

3. 03

   Upload skill → escoge el .zip

   Pica el botón Upload skill. Te abre el explorador de archivos. Le pasas un .zip que contenga tu carpeta con SKILL.md adentro. La carpeta debe llamarse exactamente igual al nombre kebab-case de la skill.

4. 04

   Toggle ON y prueba

   Ya subida, aparece en la lista con un toggle. Préndelo. En tu próxima conversación, pídele a Claude algo que dispare la skill — si la descripción está bien escrita, la cargará sola.

En Claude Code · ~/.claude/skills/<nombre>/

1. 01

   Crea la carpeta en ~/.claude/skills/

   En tu terminal, asegúrate de tener ~/.claude/skills/ creado. Adentro, crea una subcarpeta con el nombre kebab-case de tu skill (ej. ~/.claude/skills/notion-sprint-setup/).

2. 02

   Pega SKILL.md y los archivos extra

   Adentro de esa subcarpeta va el SKILL.md (con frontmatter), y opcionalmente references/, scripts/, assets/. Sin .zip — Claude Code lee la carpeta directo.

3. 03

   Reabre Claude Code y listo

   La próxima vez que arranques Claude Code en cualquier proyecto, la skill ya está disponible. No hay paso de upload. Para skills por proyecto, ponlas en <repo>/.claude/skills/ en lugar de la global.

Tip: las skills funcionan igual en Claude.ai, Claude Code y la API. Misma carpeta, mismo SKILL.md. Si una skill depende de un MCP específico (ej. Linear), asegúrate de que ese MCP también esté conectado en la superficie donde la vayas a usar.

Anthropic usa esta analogía y se entiende rápido: MCP es la cocina profesional — te da acceso a la sartén, el horno y los ingredientes (Notion, Shopify, Gmail). Las skills son las recetas — te dicen cómo combinar todo eso para sacar el platillo siempre igual. Por separado funcionan; juntos resuelven el problema completo.

Sin skill, el MCP te conecta a Linear pero el usuario tiene que saber qué tools llamar y en qué orden — cada conversación arranca de cero, los resultados son inconsistentes, y los soporte tickets se llenan de "¿cómo hago X con tu MCP?". Con skill, el workflow se activa solo cuando aplica, las llamadas al MCP van en secuencia, y el conocimiento de dominio queda embebido. Es la diferencia entre dar acceso y enseñar a usar.

La forma más rápida de crear una skill mala es empezar a escribirla sin saber qué problema resuelve. Antes de teclear nada (o antes de pasarle el prompt a la skill-creator), responde estas cuatro preguntas:

• ¿Qué quiere lograr el usuario?
• ¿Qué pasos multi-step requiere ese flujo?
• ¿Qué tools necesita — built-in (Claude solo) o MCP?
• ¿Qué conocimiento de dominio o mejores prácticas se deben embeber?

Con eso claro, tu skill cae en una de las tres categorías que Anthropic ha visto funcionar bien:

Define también criterios de éxito antes de construir: en qué porcentaje de queries esperas que se active, cuántos tokens consumir, cero llamadas API fallidas. Sin esos números, no sabes si la skill mejora o empeora.

El frontmatter es el bloque YAML al inicio del SKILL.md, entre dos líneas de tres guiones. Son las dos líneas que Claude tiene siempre cargadas. Si están bien escritas, la skill se activa cuando debe; si están mal, ni se entera. Mínimo viable:

Las cinco reglas que sí o sí hay que cumplir

1. 01

   El name va en kebab-case. Sin espacios, sin mayúsculas, sin guión bajo.

   Por qué: El nombre debe coincidir exactamente con el de la carpeta. Anthropic exige kebab-case para evitar problemas de filesystem entre OS.

2. 02

   El name no puede contener "claude" ni "anthropic".

   Por qué: Esos prefijos están reservados por Anthropic. Si los usas, el upload va a fallar al validar.

3. 03

   Nunca uses < ni > en el frontmatter.

   Por qué: El frontmatter aparece dentro del system prompt de Claude. Los corchetes XML podrían inyectar instrucciones — bloqueado por seguridad.

4. 04

   La description debe decir QUÉ hace la skill Y CUÁNDO usarla con frases-disparador concretas.

   Por qué: Es la única información que Claude tiene en cada conversación nueva. Sin trigger phrases, no la carga aunque le aplique.

5. 05

   La description máximo 1024 caracteres. El SKILL.md idealmente bajo 5,000 palabras.

   Por qué: Más allá: el contexto se infla, las respuestas se vuelven lentas o difusas. Lo extra se mueve a references/.

La description: lo único que distingue una skill que se activa de una que no

Truco rápido para validar la description: pégala en una conversación nueva con Claude y pregúntale "¿cuándo usarías esta skill?". Si las frases que cita no coinciden con lo que tus usuarios realmente dicen, reescríbela.

Después del frontmatter va el cuerpo en Markdown — las instrucciones reales. La plantilla recomendada por Anthropic para empezar es:

• # Nombre de la skill — h1 con el nombre humano.
• ## Instructions — las reglas críticas. Lo que NUNCA puede saltarse.
• ## Steps — el flujo principal numerado.
• ## Examples — uno o dos casos típicos con "el usuario dice X → Claude hace Y → resultado Z".
• ## Troubleshooting — errores comunes con causa y solución.

Cuatro reglas que separan una skill que funciona de una que no

• Específico y accionable. "Corre python scripts/validate.py --input X para verificar el formato" supera por mucho a "valida los datos antes de proceder".
• Lo crítico al inicio, no enterrado. Usa ## CRITICAL o ## Important para reglas no negociables. Repítelas si es necesario.
• Manejo de errores explícito. Para cada paso que pueda fallar, lista el error típico y los pasos de recuperación. No le dejes a Claude la improvisación.
• Detalle largo va a references/. Mantén el SKILL.md bajo 5,000 palabras. Lo demás (API patterns, edge cases, ejemplos largos) vive en archivos sueltos que Claude carga solo si los necesita.

Quiero que armes una skill nueva para mí. Esta es la idea en lenguaje natural — tú la conviertes en un SKILL.md listo para subir.

Caso de uso:
[Describe en 2-3 frases qué quieres que la skill haga. Ejemplo: "Quiero que cuando suba un PDF de un contrato, Claude me diga las cláusulas raras y me proponga cómo renegociarlas."]

Cuándo se debe activar (frases que el usuario diría):
- [Frase 1, ej: "revisa este contrato"]
- [Frase 2, ej: "qué cláusulas son raras aquí"]
- [Frase 3, ej: "ayúdame a renegociar este PDF"]

Tools que necesita:
[Built-in (Claude solo, sin MCP) o MCP específico — ej: "ninguno, solo capacidades de Claude" o "MCP de Linear para crear tasks"]

Reglas duras:
[Lo que sí o sí debe respetar. Ej: "nunca prometer monto exacto de descuento sin verificación humana"]

Lo que necesito que me devuelvas:
1. El SKILL.md completo con frontmatter (name kebab-case, description con QUÉ + CUÁNDO).
2. Sugerencias de 5 frases-disparador adicionales que se me hayan escapado.
3. Tres test queries que SÍ deberían disparar la skill, y tres que NO deberían dispararla.
4. Si la skill se beneficiaría de archivos en references/, dime qué archivos crearías y qué iría en cada uno.

No me devuelvas explicaciones largas. Solo el SKILL.md y las cuatro listas.

En este folder, arma la estructura de una skill nueva lista para subir a Claude.ai.

Nombre de la skill (en kebab-case): [tu-nombre-de-skill]

Pasos:
1. Crea la carpeta tu-nombre-de-skill/ adentro del folder actual.
2. Adentro, crea SKILL.md (mayúsculas exactas) con un frontmatter mínimo placeholder y un cuerpo template con secciones Instructions / Steps / Examples / Troubleshooting.
3. Crea las subcarpetas opcionales: references/, scripts/, assets/. En cada una pon un .gitkeep para que se mantengan vacías sin desaparecer al hacer git add.
4. NO crees README.md adentro de la carpeta de la skill — Anthropic lo prohíbe (todo va en SKILL.md o references/). Si quieres readme para humanos, créalo a nivel del repo, fuera de la carpeta de la skill.
5. Verifica que SKILL.md está en mayúsculas exactas con ls -la.
6. Cuando termines, comprime la carpeta tu-nombre-de-skill/ a tu-nombre-de-skill.zip listo para subir desde Settings → Capabilities → Skills.

Al final, dime el path exacto del .zip generado y recuérdame que el frontmatter aún tiene placeholders — debo llenarlo antes de subir.

Las skills se pueden probar a tres niveles distintos según qué tan crítica sea: manual en Claude.ai (más rápido, sin setup), scripted en Claude Code (repetible), o programático vía API (suite formal de evaluación). Para empezar, manual basta — las otras dos vienen cuando ya estás escalando.

• Triggering tests · ¿se carga cuando debe? Corre 10-20 queries que deberían disparar la skill. Anota cuántas veces se cargó sola y cuántas tuviste que invocarla a mano. Meta: 90% trigger automático.
• Functional tests · ¿produce el output correcto? Para cada caso de uso, valida que el resultado tenga el formato y contenido esperado, sin errores de API.
• Performance comparison · ¿gasta menos tokens que sin skill? Corre el mismo task con la skill prendida y apagada. Compara cuántas idas y vueltas con el modelo, cuántos tokens consumió, cuánto tardó.

¿Cuándo usarías la skill llamada "[nombre-de-tu-skill]"?

Devuélveme:
1. La descripción que tienes cargada de esa skill (cítala literal).
2. Tres ejemplos de frases del usuario que activarían esta skill.
3. Tres ejemplos de frases del usuario que NO la activarían.
4. Si la descripción te parece confusa o demasiado amplia, dime qué le mejorarías.

No ejecutes la skill — solo dime cómo decidirías si cargarla o no.

Voy a probar mi skill con queries reales. Para cada una, dime si cargarías la skill llamada "[nombre-de-tu-skill]" y por qué.

DEBERÍAN cargar la skill:
1. [Query realista 1 con vocabulario de tu dominio]
2. [Query parafraseada que el usuario también podría decir]
3. [Query con un trigger explícito de tu description]

NO DEBERÍAN cargar la skill:
4. [Query de un dominio cercano pero distinto — ej. si tu skill es de PDFs legales, esto sería de PDFs en general]
5. [Query genérica que toca palabras parecidas pero no aplica]
6. [Query completamente fuera del dominio]

Para cada una de las 6, devuélveme: "SÍ cargo la skill" o "NO cargo la skill", y la razón corta. Si los resultados no son los esperados (1-3 deben dar SÍ, 4-6 deben dar NO), apunta cuál falló para que ajuste la description.

Pro tip: la forma más efectiva de armar una skill es iterar sobre una sola tarea hasta que Claude la haga bien — y solo entonces extraer ese workflow ganador a la skill. Después extiendes a más casos.

Tengo este SKILL.md borrador. Antes de subirlo a Claude.ai, revísalo y dime qué arreglar.

```markdown
[Pega aquí tu SKILL.md completo, incluyendo el frontmatter]
```

Revisa específicamente:

1. **Frontmatter**
   - ¿El name está en kebab-case sin espacios ni mayúsculas?
   - ¿El name evita las palabras "claude" y "anthropic"?
   - ¿La description dice QUÉ hace Y CUÁNDO usarla con frases-disparador concretas?
   - ¿Está bajo 1024 caracteres?
   - ¿Tiene tags XML <> que la harían fallar?

2. **Triggers**
   - ¿Las frases-disparador son cosas que el usuario realmente diría?
   - ¿Faltan triggers obvios?
   - ¿Hay riesgo de over-triggering (que se cargue cuando no toca)?

3. **Instrucciones**
   - ¿Lo crítico está al inicio o enterrado?
   - ¿Las acciones son específicas y accionables, no genéricas?
   - ¿Incluye manejo de errores?
   - ¿Hay ambigüedad en el lenguaje?

4. **Tamaño**
   - ¿El SKILL.md pasa las 5,000 palabras?
   - ¿Hay detalle que debería ir a references/?

Dame el feedback en una lista numerada con cada problema encontrado y el fix concreto. Al final, dame el SKILL.md corregido en un solo bloque listo para pegar.

Estos cinco patrones aparecieron una y otra vez en las skills que Anthropic vio funcionar mejor con sus early adopters. No son templates rígidos — son formas de pensar el problema. Lee los cinco, identifica cuál encaja con tu caso, y la estructura del SKILL.md sale sola.

Lo difícil no es saber el patrón — es escoger el correcto. Si tu workflow tiene pasos en orden estricto, es secuencial; si toca varios servicios, es multi-MCP; si la calidad mejora con vueltas, es iterativo; si el tool depende del input, es context-aware; si necesitas reglas de compliance o decisiones legales, es domain-specific.

Estos cinco aparecen siempre. Los marco con síntoma → causa → fix concreto, y al final cierro con un checklist final que repasas antes de subir, durante el desarrollo, y después de tener la skill corriendo.

1. 01

   La skill no sube. Aparece error "Could not find SKILL.md in uploaded folder".

   Causa: El archivo no se llama exactamente SKILL.md. Es case-sensitive — skill.md, Skill.md o SKILL.MD no funcionan.

   Fix: Renombra el archivo a SKILL.md exacto. Verifica con ls -la dentro de la carpeta antes de comprimir el .zip.

2. 02

   La skill subió sin error pero Claude nunca la carga sola — siempre tienes que invocarla a mano.

   Causa: La description es vaga o no tiene frases-disparador concretas. Claude la lee y no encuentra match con lo que el usuario dijo.

   Fix: Reescribe la description con triggers específicos ("úsala cuando el usuario diga X, Y o Z"). Pídele al skill-creator que la cure.

3. 03

   Claude carga la skill cuando no toca — para preguntas que no aplican.

   Causa: La description es demasiado amplia o ambigua. No tiene negative triggers que aclaren los límites.

   Fix: Acota el dominio ("para PDFs legales, no para PDFs en general") y agrega "NO la uses para [contexto]" al final de la description.

4. 04

   La skill se carga, pero Claude no sigue las instrucciones bien o se las salta.

   Causa: El SKILL.md está demasiado verboso, las reglas críticas viven enterradas a mitad del documento, o el lenguaje es ambiguo ("asegúrate de validar" en lugar de pasos concretos).

   Fix: Pon lo crítico al inicio bajo ## CRITICAL o ## Important. Usa bullets numerados, sin párrafos largos. Mueve detalle de referencia a references/.

5. 05

   Las respuestas se sienten lentas o difusas cuando la skill está activa.

   Causa: El SKILL.md pasó las 5,000 palabras o tienes muchas skills prendidas al mismo tiempo (más de 30-50).

   Fix: Mueve la documentación detallada a references/ y deja el SKILL.md liviano. Si tienes 50+ skills, prende solo las que aplican al proyecto del momento.

Mi skill "[nombre]" no se está cargando aunque el usuario hable claramente del tema. Esta es la description actual:

"[Pega aquí la description actual]"

Estos son los queries del usuario que deberían haberla activado pero no la activaron:

1. "[Query 1]"
2. "[Query 2]"
3. "[Query 3]"

Reescribe la description para que cargue en esos casos. Reglas:
- Sigue bajo 1024 caracteres.
- Mantén la estructura QUÉ hace + CUÁNDO usarla.
- Incluye sinónimos y parafraseos que cubran los queries de arriba.
- Si hay términos técnicos del dominio que el usuario diría, agrégalos como triggers.
- Sin XML tags <> en ningún lado.

Dame solo la description nueva, sin explicación, lista para pegar en el frontmatter.

Mi SKILL.md está demasiado largo y las respuestas se sienten lentas. Lo necesito liviano con detalle separado en references/.

Lee el SKILL.md actual y haz este split:

1. **SKILL.md (queda corto)** — solo:
   - Frontmatter intacto.
   - ## Instructions con las reglas críticas (lo que NUNCA puede saltarse).
   - ## Steps con el flujo principal (sin sub-pasos detallados).
   - Links del tipo "para detalle de X, consulta references/x.md".
   - Tope: 5,000 palabras o menos. Si sigue largo, divide más.

2. **references/<tema>.md** — un archivo por tema profundo. Ejemplos:
   - references/api-patterns.md (rate limiting, paginación, error codes).
   - references/edge-cases.md (casos raros con cómo manejarlos).
   - references/examples.md (ejemplos largos).

3. En el SKILL.md original, donde había detalle ahora va una línea:
   "Antes de [acción], consulta references/<tema>.md para [propósito]."

4. Verifica que el SKILL.md final pase de las 5,000 palabras hacia abajo. Cuéntame las palabras antes y después.

Al terminar, dime el árbol de archivos resultante y el conteo de palabras del SKILL.md.

Mi skill tiene pasos críticos donde no puedo confiar en que Claude valide a mano. Necesito un script ejecutable que haga las verificaciones de forma determinista.

Contexto del paso crítico:
[Describe qué se valida. Ej: "Antes de crear un proyecto en Linear, verificar que el nombre no esté vacío, que tenga al menos un team member asignado, y que la fecha de inicio no sea pasada."]

Genera lo siguiente:

1. scripts/validate.py (o validate.sh, lo que mejor encaje):
   - Recibe los argumentos por flags (--name, --team, --start-date, etc.).
   - Hace cada verificación en orden.
   - Si todo pasa, exit code 0 con mensaje "✅ todas las validaciones pasaron".
   - Si algo falla, exit code 1 con mensaje claro de qué falló y cómo arreglarlo.

2. En el SKILL.md, en la sección donde antes decía "valida X", reemplaza por:
   "Corre `python scripts/validate.py --name {nombre} --team {team} --start-date {fecha}`. Si exit code distinto de 0, lee el mensaje, arréglalo, vuelve a correr. NO avances al siguiente paso si la validación falla."

3. Una sección ## Troubleshooting al final del SKILL.md con los errores típicos del script y cómo resolverlos.

Cuando termines, ejecuta el script con un caso válido y uno inválido para confirmar que ambos exit codes funcionan.

Checklist final · antes de cantar victoria