Tutorial de Claude Skills: Crea Tu Primera SKILL.md en 10 Minutos (2026)

Tutorial de Claude Skills: Crea Tu Primera SKILL.md en 10 Minutos (2026)

Las Skills son la funcionalidad más importante de Claude Code que probablemente no estás usando todavía. Una habilidad de Claude es una carpeta con un archivo SKILL.md que Claude carga automáticamente en el momento en que tu prompt coincide con su descripción — sin copiar y pegar prompts, sin un CLAUDE.md inflado, sin tener que recordar qué plantilla usar. Hemos publicado 4 habilidades dentro de la carpeta .claude/skills/agent/ de este repositorio, y con Skills 2.0 más el Anthropic Marketplace que llegó a principios de 2026, el formato por fin alcanza su mejor momento. Aquí está el patrón que funciona después de tropezar con los errores típicos.

Puntos clave

• Una habilidad de Claude es una carpeta con un archivo SKILL.md y frontmatter YAML que Claude carga automáticamente cuando es relevante.
• Las habilidades viven en ~/.claude/skills/ (personal) o .claude/skills/ (proyecto) — Claude escanea ambas al arrancar.
• Usa Skills para flujos de trabajo reutilizables; usa MCP para datos externos en tiempo real; usa subagentes para planificación multietapa; usa hooks para eventos deterministas.
• El camino más rápido a tu primera habilidad es pedirle a Claude que invoque su propia habilidad skill-creator — escribe el SKILL.md por ti.

¿Qué Son las Claude Skills?

Una habilidad de Claude es una carpeta con un archivo SKILL.md con frontmatter YAML (name, description, allowed-tools opcional) que Claude Code carga automáticamente al contexto cuando tu prompt coincide con la descripción. Las Skills empaquetan flujos de trabajo reutilizables — como /commit o /explain-code — sin saturar el prompt del sistema.

Según la documentación oficial de Anthropic, cada carpeta de habilidad tiene tres cosas: un SKILL.md obligatorio, scripts opcionales incluidos (desde un helper de Python hasta una configuración JSON) y documentación de referencia opcional que se carga junto con el cuerpo. Eso es todo. Sin paso de compilación, sin instalación, sin manifiesto.

Lo ingenioso es la divulgación progresiva. Al arrancar, Claude solo escanea el campo description de cada habilidad. El cuerpo — instrucciones, ejemplos, patrones de llamada a herramientas — permanece en disco hasta que tu prompt coincide. Así que puedes tener 50 habilidades instaladas y no pagar ningún coste en tokens hasta que una se active.

Piensa en las habilidades como recetas de un libro de cocina que Claude consulta cuando ve los ingredientes en tu prompt. Una habilidad es una carpeta que Claude lee bajo demanda — no un prompt que tienes que recordar pegar. Esa es toda la propuesta.

Un SKILL.md mínimo tiene esta pinta:

---
name: Summarize file
description: Use when the user asks for a 3-sentence summary of a file or function.
---

Read the file at $ARGUMENTS. Summarize purpose, key dependencies, and the
single most surprising thing about it. Three sentences max.

Diez líneas. Una habilidad real. Lista para activarse.

Inicio Rápido: Crea Tu Primera Habilidad en 10 Minutos

Para crear tu primera habilidad de Claude en 10 minutos: (1) crea ~/.claude/skills/explain-code/, (2) añade un archivo SKILL.md con name, description y el cuerpo del flujo de trabajo, (3) reinicia Claude Code para que escanee el nuevo directorio, (4) actívala con un prompt que coincida con la descripción.

Aquí está el flujo completo.

Paso 1: Crea el directorio

mkdir -p ~/.claude/skills/explain-code

Las habilidades personales (solo para ti) van en ~/.claude/skills/. Las habilidades de proyecto (compartidas con tu equipo vía git) van en .claude/skills/ en la raíz del repositorio. Elige personal para flujos de trabajo de uso diario; elige proyecto cuando quieras que todos los colaboradores del repositorio lo hereden.

Paso 2: Escribe SKILL.md

Coloca este archivo en ~/.claude/skills/explain-code/SKILL.md:

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
---

You are explaining code to a developer who is new to this codebase.

1. Read the file or snippet at $ARGUMENTS.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies or side effects.
5. End with one question the reader should ask before changing this code.

Esa es la habilidad completa. El frontmatter es el contrato; el cuerpo es el manual.

Paso 3: Reinicia Claude Code

La detección en tiempo real es una funcionalidad de Skills 2.0 — las versiones anteriores de Claude Code necesitan un reinicio para detectar el nuevo directorio. Si no estás seguro de qué versión tienes, reiniciar una vez no cuesta nada.

Paso 4: Actívala

Abre un proyecto y escribe:

walk me through what auth/middleware.ts does

Claude compara tu prompt contra el campo description, encuentra explain-code y carga silenciosamente el cuerpo del SKILL.md al contexto. Verás "Using skill: explain-code" en el registro de herramientas. Listo.

Consejo pro: ¿No te apetece escribir el archivo tú mismo? Abre Claude Code y di Use the skill-creator skill to scaffold an explain-code skill for me. El skill-creator incluido por Anthropic es una meta-habilidad que te hace preguntas, elige unos allowed-tools razonables y escribe el SKILL.md en la carpeta correcta. El camino más rápido a tu primera habilidad, sin discusión.

Esa es la promesa de 10 minutos — cinco minutos escribiendo, un reinicio, un prompt de prueba.

Dentro de SKILL.md: Referencia del Frontmatter

El frontmatter de SKILL.md es YAML delimitado por ---. Dos campos son obligatorios: name (máx. 64 caracteres, se usa como nombre del comando slash) y description (el texto de activación que Claude compara con tu prompt). Los campos opcionales controlan el acceso a herramientas, la invocación del modelo, patrones glob de archivos y el contexto de ejecución.

Aquí está la referencia completa, extraída de la documentación de habilidades de Anthropic:

La fila context: fork merece una mención especial. Es una primitiva de Skills 2.0 que ejecuta la habilidad dentro de una ventana de contexto aislada — útil para habilidades de investigación de larga duración o cualquier cosa que produzca muchos tokens intermedios que no quieres que contaminen tu hilo principal. Si esto te resulta nuevo, nuestra guía de context engineering cubre los pros y los contras.

Un frontmatter maximista de SKILL.md, con todos los campos:

---
name: Deploy preview
description: Use when the user wants to deploy a preview build of the current branch to staging.
allowed-tools: ["Bash(git status:*)", "Bash(npm run build:*)", "Bash(vercel:*)"]
disable-model-invocation: true
user-invocable: true
argument-hint: <branch-name or 'current'>
model: claude-opus-4-7
context: fork
globs: ["package.json", "vercel.json"]
references: ["./deploy-runbook.md"]
bundled-files: ["./scripts/preflight.sh"]
tags: ["deploy", "vercel", "preview"]
---

Consejo pro: El error más grave en description es escribirlo para humanos. Escríbelo para Claude — frases de activación concretas, no texto de marketing. Mal: "Una potente habilidad de automatización de Git." Bien: "Use when the user wants to commit changes, write a commit message, or open a PR."

Dos Habilidades Reales, de Principio a Fin

Dos patrones de habilidades cubren el 80 % de los casos de uso reales: (1) una habilidad /commit invocable por el usuario con disable-model-invocation: true y allowed-tools: Bash(git *) para acciones deterministas; (2) una habilidad /explain-code auto-invocada con frontmatter por defecto que Claude activa cuando los prompts coinciden con su descripción.

La mayoría de los tutoriales muestran fragmentos. Aquí tienes dos archivos completos que puedes copiar en ~/.claude/skills/ hoy mismo.

La habilidad /commit (invocable por el usuario)

---
name: Commit
description: Use when the user wants to stage and commit code changes with an AI-written conventional-commit message.
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git diff:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
---

1. Run `git status` and `git diff` to see what's staged and unstaged.
2. Group changes into one logical commit. If there are multiple unrelated
   changes, ask the user which to include.
3. Draft a Conventional Commits message: `type(scope): subject` (≤72 chars),
   blank line, body explaining *why*, not *what*.
4. Show the message to the user. Ask "Commit this?" Wait for explicit yes.
5. On confirmation, run `git add` for the included files and `git commit -m`.
6. Print the resulting commit hash.

Prompt de prueba: /commit

Qué ocurre: Claude inspecciona el estado de git, redacta un mensaje, te pide confirmación y solo entonces ejecuta git commit. El disable-model-invocation: true significa que nunca se activa automáticamente ante un vago "guarda mis cambios" — solo se ejecuta cuando escribes /commit. La lista blanca de allowed-tools lo restringe a subcomandos de git; físicamente no puede ejecutar rm -rf ni hacer push al remoto. Esta es una habilidad que usamos en producción en nuestro propio pipeline.

Para acciones deterministas posteriores al commit (ejecutar lint, regenerar tipos, enviar un webhook a Slack), usa los hooks de Claude Code — las habilidades son probabilísticas, los hooks se disparan siempre.

La habilidad /explain-code (invocable por el modelo)

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
argument-hint: <file path or pasted snippet>
model: claude-opus-4-7
---

1. Read the file or snippet at $ARGUMENTS. If $ARGUMENTS is empty, ask
   the user which file to explain.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies, side effects, or hidden assumptions.
5. End with one question the reader should ask before modifying this code.

Prompt de prueba: walk me through what auth/middleware.ts does

Qué ocurre: fíjate en que el usuario no escribió /explain-code. Claude compara "walk me through" contra el campo description, encuentra la habilidad y la invoca automáticamente. Esa es la magia — la description hace el enrutamiento. El campo model: claude-opus-4-7 fija esta habilidad a Opus independientemente del modelo que hayas configurado como predeterminado, de modo que los análisis profundos de código siempre obtienen el modelo más capaz. (Más sobre cómo ejecutar Claude Code con diferentes modelos.)

¿Por qué dos patrones? La habilidad #1 es invocable por el usuario y está restringida a herramientas específicas — predecible, segura, perfecta para git o despliegues. La habilidad #2 es auto-invocada y de propósito general — la magia de las skills, pero confía en tu campo description. Las habilidades invocables por el usuario dan predecibilidad; las invocables por el modelo dan magia. Elige por habilidad, no por repositorio.

Para más ejemplos reales, consulta el repositorio oficial anthropics/skills y la lista mantenida por la comunidad awesome-claude-skills.

Skills vs. MCP vs. Subagentes vs. Hooks: ¿Cuándo Usar Qué?

Usa Skills para flujos de trabajo reutilizables que Claude debe auto-activar o que invocas como comandos slash. Usa servidores MCP cuando necesites datos externos en tiempo real (bases de datos, APIs, sistemas de archivos más allá del directorio de trabajo). Usa subagentes para planes multietapa que Claude debe delegar a un contexto nuevo. Usa hooks para eventos deterministas (pre-commit, post-tool-use) que deben dispararse siempre — nunca de forma probabilística.

Encuadre rápido: las skills son flujos de trabajo, el Model Context Protocol es datos, los subagentes son planes, los hooks son eventos. Cada uno vive en una capa diferente de Claude Code, y la capa equivocada es la herramienta equivocada. Según el post de Anthropic Skills explained, este es el encuadre que quieren que interiorices.

Se complementan entre sí. Una habilidad puede llamar a una herramienta MCP a través de allowed-tools. Un hook puede dispararse después de que una habilidad se complete. Un subagente puede usar las habilidades a las que se le ha dado acceso. El modelo mental más claro: elige la capa correcta primero y luego deja que se apilen. Las Skills son la primitiva de context engineering a la que acudes cuando quieres un flujo de trabajo que Claude pueda elegir; automatiza con hooks cuando quieres algo que Claude no pueda saltarse.

El peor uso de cada una: Skills para datos en tiempo real (usa MCP); MCP para plantillas de prompt de un solo uso (usa Skills); subagentes para ediciones de archivos deterministas (usa hooks); hooks para lógica ramificada (usa Skills). Skills son flujos de trabajo, MCP son datos, subagentes son planes, hooks son eventos. Elige por la capa, no por la palabra de moda.

Dónde Viven las Skills: Personal, Proyecto, Plugin, Empresa

Las habilidades de Claude se instalan en cuatro ámbitos: personal (~/.claude/skills/, solo tú), proyecto (.claude/skills/ en la raíz del repositorio, tu equipo vía git), plugin (distribuido vía el Anthropic Marketplace o cualquier URL de plugin) y empresa (distribuido por IT a través de MDM/política de administración). Claude escanea los cuatro al arrancar.

Las habilidades de documentos incluidas son fáciles de olvidar — Claude Code ya viene con habilidades para pdf, docx, pptx y xlsx de serie, además de una pequeña biblioteca de /debug, /simplify y similares integradas. (La herramienta hermana Claude Design viene con sus propias habilidades de flujo de trabajo incluidas para generación de diseño; mismo modelo, dominio diferente.)

¿Cuándo distribuyes vía plugin en lugar de proyecto? Los plugins ganan cuando el mismo flujo de trabajo beneficia a varios repositorios — una habilidad /release que usas en cinco bases de código de clientes pertenece a un plugin, no copiar-pegar en el .claude/skills/ de cada repositorio. Las habilidades de proyecto ganan para convenciones específicas del código base (tu plantilla de PR del equipo, tu test runner personalizado). El Anthropic Marketplace, más /plugin install desde cualquier URL, hace que los plugins sean la respuesta correcta para la reutilización entre repositorios. Según la documentación de plugins, el descubrimiento y las actualizaciones se manejan automáticamente.

Patrones Avanzados: $ARGUMENTS, Inyección Dinámica de Shell, context: fork

Tres patrones avanzados de habilidades son los más importantes: $ARGUMENTS permite a los usuarios pasar parámetros a habilidades invocables por el usuario (/translate $ARGUMENTS); la inyección dinámica de shell (con allowed-tools: Bash(...)) permite a una habilidad ejecutar scripts y llevar la salida al contexto; y context: fork (Skills 2.0) ejecuta la habilidad en una ventana de contexto aislada. El whitepaper Complete Guide de Anthropic es la referencia canónica para context: fork a mayo de 2026.

$ARGUMENTS para habilidades parametrizadas

---
name: Translate
description: Translate the most recent message into the target language.
user-invocable: true
argument-hint: <target-language, e.g. spanish, japanese, brazilian portuguese>
---

Translate the user's previous message into $ARGUMENTS. Preserve tone,
preserve markdown formatting, return only the translation.

Prompt de prueba: /translate spanish. Claude sustituye spanish por $ARGUMENTS en tiempo de ejecución. La forma más limpia de hacer una habilidad multipropósito sin escribir variantes.

Inyección dinámica de shell vía allowed-tools

---
name: Review last commit
description: Use when the user wants a code review of the last git commit.
allowed-tools: ["Bash(git diff HEAD~1:*)", "Bash(git log -1:*)"]
---

Run `git diff HEAD~1` and `git log -1`. Review the diff for bugs, security
issues, and style violations. Output a 5-bullet review.

La habilidad lanza el shell, lleva el diff al contexto y lo revisa. Restringe allowed-tools a comandos específicos (Bash(git diff HEAD~1:*)), nunca Bash a secas — el permiso bare Bash es la versión con la pistola apuntándote al pie de este patrón.

context: fork (Skills 2.0)

---
name: Deep research
description: Use when the user wants a multi-source research summary on a topic.
context: fork
---

Research the topic in $ARGUMENTS using available web tools. Produce a
2-page summary with citations. Do not pollute the main thread.

El fork le da a la habilidad su propia ventana de contexto, de modo que los 50K tokens de notas intermedias de investigación no se filtran a tu sesión principal. Útil para investigaciones largas, planificación de grandes refactorizaciones o cualquier cosa que genere muchos tokens desechables. Solo Skills 2.0 — las versiones anteriores de Claude Code ignoran el campo.

Solución de Problemas: Por Qué Tu Habilidad No Se Activa

Las habilidades suelen fallar en activarse por uno de cuatro motivos: (1) la description es demasiado genérica para que Claude la empareje con tu prompt, (2) el directorio está en la ruta incorrecta (.claude/skills/ sin el punto no existe), (3) Claude Code no se reinició después de añadir la habilidad (solo en versiones pre-Skills-2.0), o (4) el nombre de la habilidad entra en conflicto con una habilidad incluida o de mayor prioridad. Según los modos de fallo más buscados en el rastreador de issues de Claude Code en GitHub, estos cuatro cubren ~95 % de los informes de "¿por qué no funciona esto?".

Modo de fallo 1: "Mi habilidad no aparece en absoluto"

La causa número uno es una ruta incorrecta — .claude/skills/ (con el punto) vs. claude/skills/ (sin punto) es una errata que todos hemos cometido a la 1 de la mañana. Ejecuta ls -la ~/.claude/skills/ para confirmar que el directorio existe con el punto. Si está ahí y Claude sigue sin verlo, reinicia Claude Code una vez. Las versiones pre-Skills-2.0 solo escanean al arrancar.

Modo de fallo 2: "Claude no invoca automáticamente mi habilidad"

El campo description es demasiado vago o está escrito para humanos, no para Claude. Reescríbelo con frases de activación concretas que reflejen cómo los usuarios formulan realmente sus peticiones. Después de construir 4 habilidades para este repositorio, el error en el que caí fue dejar descripciones como "A helpful skill for SEO." Inútil. Reescribe así: "Use when the user wants to add JSON-LD schema, meta tags, or SEO frontmatter to a Markdown post." La precisión de activación pasó de ~30% a ~95%. La precisión de activación vive o muere en el campo description. Escríbelo para Claude, no para tu currículum.

Modo de fallo 3: "La descripción se cortó en la paleta de comandos slash"

O tu description supera los 1024 caracteres o tu name supera los 64 caracteres. Ambos tienen límites estrictos. Solución: divide la habilidad en dos más específicas, o mueve el detalle largo al cuerpo del SKILL.md. El frontmatter es para el enrutamiento, no para la documentación.

Modo de fallo 4: "La detección de cambios en tiempo real no funciona"

Claude Code pre-Skills-2.0 requiere un reinicio completo después de cualquier edición de SKILL.md. Si estás iterando en una habilidad y tus cambios no surten efecto, probablemente estés en una versión antigua. Actualiza a una versión de Claude Code que incluya Skills 2.0 (detección en tiempo real) o acostúmbrate a reiniciar después de cada guardado. Molesto, pero rápido.

Skills Más Allá de Claude: El Estándar Abierto Agent Skills

Sí — las skills son un estándar abierto. El estándar Agent Skills en agentskills.io define el formato SKILL.md de forma independiente a cualquier proveedor. El CLI Codex de OpenAI y ChatGPT Desktop adoptaron el estándar en diciembre de 2025; el mismo SKILL.md que escribes para Claude Code funciona en Codex con pequeños ajustes de frontmatter.

Aquí está la matriz de compatibilidad entre herramientas a mayo de 2026: Claude Code tiene soporte completo de Agent Skills (la implementación de referencia). El CLI Codex de OpenAI tiene soporte completo. ChatGPT Desktop tiene soporte parcial — name, description y el cuerpo funcionan, pero la paridad de allowed-tools aún no está disponible. Gemini CLI anunció soporte a principios de 2026 pero no lo había lanzado en el momento de escribir esto. Cursor es el caso atípico — usa su propio formato de Cursor rules y no lee SKILL.md de forma nativa, aunque existen shims de la comunidad.

Qué escribir hoy para que tus skills sobrevivan el año: mantén name y description limpios y agnósticos a la herramienta. Aísla cualquier frontmatter específico de un proveedor tras un espacio de nombres (claude: o codex:) si vas a usar varias herramientas. La superficie portable — name, description, body, $ARGUMENTS — funciona en todas partes; los campos avanzados como context: fork son específicos de Claude hasta que otros proveedores implementen sus equivalentes. Anthropic también está impulsando una integración más profunda con el marketplace según el roadmap filtrado de Claude Code, así que la portabilidad solo va a mejorar.

Los tres lugares donde buscar ejemplos de habilidades: anthropics/skills (oficial), awesome-claude-skills (comunidad) y agentskills.io (la página de especificación del estándar). Las Skills ya no son una funcionalidad de Claude. Son un estándar abierto que Claude lanzó primero.

FAQ

¿Cuál es la diferencia entre una Claude Skill y un servidor MCP?

Una habilidad de Claude es un archivo SKILL.md con instrucciones de flujo de trabajo que Claude carga cuando tu prompt coincide con su descripción. Un servidor MCP es un proceso separado que Claude llama para obtener datos en tiempo real (bases de datos, APIs, sistemas de archivos más allá del directorio de trabajo). Usa Skills para flujos de trabajo; usa MCP para datos. Se complementan — las skills pueden llamar a herramientas MCP.

¿Son gratuitas las Claude Skills?

Sí — Skills es una funcionalidad integrada de Claude Code, sin cargo adicional. Solo pagas por los tokens del modelo consumidos cuando se ejecuta una habilidad. Las skills que instales desde el Anthropic Marketplace pueden ser de pago (raro hoy en día), pero el repositorio oficial anthropics/skills y las listas de la comunidad son todas gratuitas para copiar y usar.

¿Dónde se instalan las Claude Skills?

Las habilidades personales van en ~/.claude/skills/{nombre-habilidad}/, las habilidades de proyecto en .claude/skills/{nombre-habilidad}/ en la raíz del repositorio. Las habilidades plugin se instalan vía /plugin install <url> y viven en tu directorio de plugins. Las habilidades de empresa son distribuidas por el IT de tu organización a través de ajustes gestionados. Claude Code escanea los cuatro ámbitos al arrancar.

¿Cómo creo una Claude Skill desde cero?

Crea una carpeta en ~/.claude/skills/, añade un archivo SKILL.md con frontmatter YAML (name, description) seguido de las instrucciones del flujo de trabajo, y reinicia Claude Code. El camino más rápido: abre Claude Code y pídele que invoque la habilidad skill-creator incluida — crea el andamiaje del SKILL.md en menos de un minuto.

¿Por qué no se activa mi Claude Skill?

Las cuatro causas más comunes: (1) la description es demasiado vaga para que Claude la empareje con tu prompt — reescríbela con frases de activación concretas; (2) la habilidad está en la ruta incorrecta (.claude/skills/ no claude/skills/); (3) Claude Code necesita reiniciarse en versiones pre-Skills-2.0; (4) el nombre de la habilidad entra en conflicto con una habilidad incluida. Verifica con ls -la ~/.claude/skills/.

¿Pueden ChatGPT o Cursor usar Claude Skills?

ChatGPT Desktop y Codex CLI soportan el mismo estándar Agent Skills que Claude — el mismo SKILL.md funciona en ambos con cambios menores de frontmatter. Cursor usa su propio formato de Cursor rules y no lee SKILL.md de forma nativa. Gemini CLI anunció soporte a principios de 2026 pero no lo había lanzado a mayo de 2026.

¿Qué es la habilidad skill-creator?

skill-creator es una meta-habilidad incluida en el repositorio anthropics/skills que ayuda a Claude a escribir nuevos archivos SKILL.md. Dile a Claude qué quieres que haga la habilidad; skill-creator te hace preguntas sobre la descripción, elige unos allowed-tools razonables y escribe el SKILL.md en la carpeta correcta. El andamiaje más rápido posible.

¿Qué hace disable-model-invocation?

Establecer disable-model-invocation: true en el frontmatter de tu habilidad impide que Claude active la habilidad automáticamente basándose en la coincidencia de prompts. La habilidad pasa a ser invocable solo por el usuario — aparece en la paleta de comandos slash como /nombre-habilidad y solo se ejecuta cuando se llama explícitamente. Úsalo para acciones destructivas o deterministas como /commit o /deploy.

Construye unas pocas habilidades, distribúyelas en un proyecto, y observa qué funciona. Si tu equipo sigue tropezando con el conjunto de problemas de "habilidad no se activa" en varios repositorios y quieres que alguien revise tu configuración de .claude/skills/, contáctanos — con gusto lo analizamos juntos.