Habilidades de Código Claude: Archivos SKILL.md que el Modelo Invoca

Última actualización: June 28, 2026

Una Claude Code Skill es una carpeta con un archivo SKILL.md que el agente carga en contexto solo cuando una tarea coincide con ella. Creé mi primera skill para dejar de pegar la misma lista de verificación de migración de base de datos de 200 palabras en cada sesión. Ese único archivo ahora me ahorra aproximadamente una hora a la semana.

Aquí está la versión corta, y luego la anatomía práctica: qué es una skill, cómo escribir el frontmatter y el cuerpo de SKILL.md, cómo decide el modelo invocar una skill, y cuándo una skill es excesiva en comparación con un prompt simple. Si ya usas Claude Code, puedes implementar tu primera skill en menos de cinco minutos.

Respuesta rápida: ¿qué es una Claude Code Skill?

Una skill es una capacidad reutilizable invocada por el modelo y almacenada como SKILL.md (más scripts de soporte opcionales). A diferencia de un prompt de sistema que siempre se carga, una skill se carga bajo demanda cuando el modelo decide que es relevante para tu solicitud. Tú escribes un nombre, una descripción de cuándo usarla y las instrucciones del cuerpo. La descripción es el campo más importante, porque es lo que el modelo lee para decidir si debe activar la skill. Las skills viven localmente en .claude/skills/ o se envían desde un registro, por lo que un equipo puede compartir una manera canónica de realizar migraciones, revisiones de código o lanzamientos.

Si deseas un contexto más amplio sobre el CLI en sí, consulta mi guía definitiva de Claude Code para 2026. Para saber cómo difieren las skills de los subagentes siempre activos, lee cómo automatice mi flujo de trabajo con Claude Code sub-agents.

¿Qué es realmente una skill y de qué está hecha?

Una skill es un directorio. El mínimo que necesita es un archivo SKILL.md. Opcionalmente, puede agrupar scripts, plantillas o documentos de referencia que viajan con la skill. La documentación de agent-skills de Anthropic describe una skill como un conjunto empaquetado de instrucciones y recursos que el modelo puede cargar cuando es relevante (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Pienso en una skill como una subrutina nombrada y versionada para el modelo. Tres cosas la hacen diferente de un prompt largo:

1. Es opcional. El modelo la carga solo cuando una tarea parece coincidir con la descripción.
2. Está acotada (scoped). Puedes adjuntar archivos y scripts que solo tienen sentido para esa capacidad.
3. Es compartible. La carpeta es portable entre proyectos y compañeros de equipo.

El CLI en sí es de código abierto y la convención de skills está documentada junto a él en GitHub (github.com/anthropics/claude-code), que es donde reviso cuándo cambian los comportamientos entre lanzamientos.

¿Cómo estructurar un archivo SKILL.md?

El archivo tiene dos partes: el frontmatter YAML y un cuerpo Markdown. El frontmatter le dice al modelo cuándo ejecutarlo; el cuerpo le dice qué hacer. Aquí está la anatomía que utilizo.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

El cuerpo es Markdown simple. Mantengo tres secciones: un objetivo de una línea, un procedimiento numerado y una puerta explícita de "detenerse y confirmar". El name debe coincidir con el nombre de la carpeta. La description debe escribirse para el modelo, no para un humano, por lo que debe leerse como una condición de activación.

Lo probé directamente. Con una descripción vaga como "ayuda con bases de datos", la skill se activaba en preguntas de SQL no relacionadas. Después de reescribirla a "Use when the user asks to create, modify, or roll back a database migration" (Úsalo cuando el usuario pida crear, modificar o revertir una migración de base de datos), la precisión de invocación pasó de aproximadamente un 60 por ciento a ser fiable. La descripción está haciendo el enrutamiento, así que dedica tu tiempo de edición allí.

¿Cuándo deberías convertir algo en una skill?

Esta es la pregunta que más recibo. Mi regla: si he pegado el mismo bloque de instrucciones tres veces en dos semanas, y es más largo que un párrafo, se convierte en una skill. A continuación está la matriz de decisión que realmente utilizo.

El segundo eje es el costo. Cada skill cargada añade tokens al contexto, por lo que un bloque de instrucciones grande y siempre relevante es mejor como una memoria a nivel de proyecto o un comando personalizado que como una skill. Las skills brillan para la experiencia condicionalmente relevante.

Un caso concreto donde escribí una skill: nuestro proceso de lanzamiento requiere actualizar un registro de cambios (changelog), incrementar tres archivos de versión, etiquetar y publicar un resumen en Slack. Lo escribí una vez como una skill, y ahora digo "cut a release" (realizar un lanzamiento) y el modelo ejecuta toda la lista de verificación en orden. Un caso concreto donde no lo hice: un refactor único de un archivo de configuración. Eso se mantuvo como un prompt.

¿Cómo funciona el patrón de skill invocado por el modelo?

El patrón que hace que las skills parezcan mágicas es que tú no las llamas. Tú describes el trabajo, y el modelo lee las descripciones de las skills disponibles y carga la coincidente. Esto está documentado en los documentos oficiales de Claude Code (docs.anthropic.com/en/docs/claude-code).

El flujo es el siguiente:

1. Escribes una solicitud en lenguaje natural.
2. El modelo ve el name y la description de cada skill instalada.
3. Puntúa la relevancia con respecto a tu solicitud.
4. El cuerpo de la skill ganadora (y los archivos empaquetados) entran en contexto.
5. El modelo ejecuta las instrucciones.

La consecuencia práctica: debes escribir la description como si estuvieras escribiendo una entrada de motor de búsqueda para el modelo. Empieza con el verbo y el alcance del disparador. Compara estas dos descripciones:

• Débil: "Una skill para manejar cosas de git."
• Fuerte: "Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite." (Úsalo cuando el usuario pida hacer squash, rebase o dividir commits en la rama actual. Produce un plan interactivo antes de ejecutar cualquier reescritura.)

La fuerte nombra los verbos disparadores y las salvaguardas. Eso es lo que hace que la invocación sea fiable. Si estás conectando skills con herramientas, la guía de integración MCP de Claude Code cubre cómo encajan los servidores de herramientas externos junto con los paquetes de skills. Para el protocolo subyacente que los conecta, consulta MCP y el contexto del modelo.

¿Cómo activar y depurar una skill?

Activar es en su mayoría automático, pero tengo tres técnicas deliberadas para el control y la depuración.

• Ser explícito. Decir "use the safe-migration skill" (usa la skill de migración segura) lo fuerza. Útil cuando la descripción es ambigua.
• Listar skills instaladas. Pídele al modelo que liste las skills disponibles y sus descripciones. Así confirmo que una nueva skill está registrada.
• Inspeccionar el rastreo (trace). Cuando una skill se activa incorrectamente, leo qué descripción coincidió y ajusto la redacción del disparador.

Cuando una skill no se activa, la causa es casi siempre la descripción, no la ubicación del archivo. Reescribo la primera frase para que comience con "Use when..." (Úsalo cuando...) y añado los verbos específicos. Eso lo soluciona nueve de cada diez veces.

Aquí está la lista de verificación de depuración que reviso, en orden:

Skill versus sub-agente versus comando de barra (slash command)

Estos tres se superponen, y la gente los confunde constantemente. Yo los mantengo separados con una división simple.

• Skill: instrucciones invocadas por el modelo más archivos opcionales. Mejor para experiencia condicional.
• Sub-agente: una instancia separada de Claude Code que realiza un trabajo aislado. Mejor para tareas paralelas y de larga duración. Mi escrito sobre automatización con sub-agents profundiza en esto.
• Comando de barra (Slash command): un atajo que escribes deliberadamente. Mejor para cosas que siempre quieres bajo demanda.

Las skills son las únicas de las tres que el modelo elige por ti. Ese es su superpoder y su riesgo: una skill mal descrita desperdicia contexto en silencio.

¿Cómo se comparten las skills y cómo se usa un registro?

Una skill es solo una carpeta, por lo que compartirla es trivial en principio. Coloco la carpeta bajo .claude/skills/ en el repositorio y hago commit. Los compañeros de equipo lo obtienen al clonar. Para compartir entre equipos, la comunidad mantiene registros (registries) y las herramientas oficiales apuntan a ubicaciones comunes.

Mi configuración práctica:

1. Mantener skills específicas del proyecto en el repo, controladas por versiones.
2. Mantener skills personales en un repo de dotfiles enlazado simbólicamente a .claude/skills/.
3. Fijar las versiones de las skills al compartir externamente, ya que un cambio en la descripción puede cambiar silenciosamente el comportamiento.

La advertencia honesta sobre compartir: una skill codifica suposiciones sobre tu stack. Una skill de migración escrita para Drizzle producirá con confianza resultados incorrectos en un proyecto Prisma si la descripción no protege el alcance. Siempre declara el framework y las salvaguardas en la descripción, y añade un paso de "detenerse y confirmar" antes de acciones destructivas. Aprendí esto por las malas cuando una skill compartida ejecutó una reescritura destructiva en la rama equivocada, así que trata cada skill compartida como no confiable hasta que su descripción demuestre lo contrario.

Créditos de imágenes

• Pantalla negra con texto de código superpuesto en una estación de trabajo de desarrollador — foto por Pixabay en Pexels
• Primer plano de código de programación en un monitor durante el desarrollo — foto por Christina Morillo en Pexels
• Portátil mostrando un editor de código durante el desarrollo de software — foto por luis gomes en Pexels