Crea tu primera skill de Claude Code: guía completa desde cero

Hay tareas que repetimos una y otra vez cuando trabajamos con IA: revisar una pull request, comprobar los mensajes de commit, preparar documentación, generar contenido, validar un formato o seguir las convenciones de un proyecto. Explicárselas a Claude Code cada vez funciona, claro. Pero no es precisamente la forma más inteligente de trabajar. Una skill de Claude Code sirve justo para eso: convertir una instrucción que ya conoces en una habilidad reutilizable. La defines una sola vez y Claude puede aplicarla cuando corresponda, sin que tengas que volver a redactar el mismo prompt una y otra vez.

No es un plugin, no es un modelo nuevo y tampoco hay magia oscura. Es, literalmente, texto bien organizado. Y cuando empiezas a crear skills para tu forma de trabajar, el salto de productividad es enorme.

Qué es una skill de Claude Code

Una skill de Claude es una carpeta que contiene un archivo llamado SKILL.md. La carpeta lleva el nombre de la habilidad y el archivo define qué debe hacer Claude cuando esa habilidad se activa.

Ese archivo tiene dos partes muy claras:

• Front matter: la cabecera entre tres guiones, donde indicas el nombre y la descripción.
• Body: el cuerpo del archivo, donde escribes las instrucciones detalladas, los pasos y las condiciones que Claude debe seguir.

La idea es muy sencilla: el front matter permite a Claude decidir si esa skill tiene relación con la petición actual. Si la respuesta es sí, entonces carga el cuerpo completo de la habilidad y ejecuta las instrucciones.

Esto tiene una consecuencia importantísima: la descripción no es decorativa. Es el criterio que utiliza Claude para saber cuándo debe emplear una skill y cuándo debe dejarla quietecita.

Piensa en una caja de herramientas. Dentro puedes tener martillos, destornilladores, alicates y un taladro. No usas el taladro para todo, ni sacas toda la caja cada vez que necesitas apretar un tornillo. Claude funciona igual: una buena descripción le permite identificar qué herramienta toca utilizar en cada momento.

Además, esto ayuda con los tokens. Claude solo necesita leer el nombre y la descripción para valorar si la skill aplica. El body completo, que puede contener instrucciones más largas, se carga únicamente cuando hace falta. Por eso merece tanto la pena escribir títulos y descripciones precisos.

Skills de proyecto y skills globales: dónde deben vivir

Hay dos ubicaciones principales para guardar una skill de Claude y elegir mal es uno de los motivos más habituales por los que parece que una habilidad ha desaparecido.

Skill de Claude de proyecto

Una skill de proyecto se guarda dentro del repositorio, en esta ruta:

.claude/skills/nombre-de-la-skill/SKILL.md

Por ejemplo, una skill para resumir pull requests podría vivir aquí:

.claude/skills/resumen-pr/SKILL.md

Esta opción es la correcta cuando la habilidad depende del contexto del proyecto: su stack tecnológico, sus convenciones de código, la estructura de carpetas, los scripts existentes o las reglas del equipo.

Como forma parte del repositorio, puedes subirla a Git junto al resto del código. Así, cualquier compañero que clone el proyecto podrá utilizar exactamente la misma skill.

Skill de Claude global

Una skill global vive en tu máquina, dentro de tu carpeta personal:

~/.claude/skills/nombre-de-la-skill/SKILL.md

Esta habilidad estará disponible en todos los proyectos que abras con Claude Code desde ese ordenador. Es perfecta para procesos personales que no dependen de un repositorio concreto, como tus preferencias de redacción, una rutina para organizar notas o una forma determinada de revisar tareas.

La regla es bastante limpia: si la skill de Claude pertenece al proyecto, va en .claude/skills. Si pertenece a tu manera personal de trabajar y la quieres en todas partes, va en ~/.claude/skills.

Crea tu primera skill de Claude a mano

Vamos con un caso realista y muy útil: una habilidad para resumir una pull request antes de aprobarla.

Crea estas carpetas dentro de tu proyecto:

.claude/ └── skills/     └── resumen-pr/         └── SKILL.md

En el archivo SKILL.md, empieza definiendo una cabecera clara. El nombre debe ser reconocible y la descripción tiene que explicar con precisión qué hace la skill y cuándo debe utilizarse.

--- name: resumen-pr description: Resume una pull request explicando qué cambia, por qué cambia y qué partes deben revisarse con más cuidado. Úsala cuando el usuario comparta un diff o pida revisar una pull request antes de aprobarla. ---  Analiza los cambios aportados y redacta un resumen estructurado.  1. Explica el objetivo principal de la pull request. 2. Enumera los cambios relevantes. 3. Señala posibles riesgos, regresiones o zonas que requieren una revisión más cuidadosa. 4. Si falta contexto, pide la información necesaria antes de emitir una conclusión.

Con esto ya tienes una skill funcional. Puedes invocarla manualmente con una barra y su nombre, por ejemplo /resumen-pr, o dejar que Claude la detecte automáticamente por contexto.

Por qué una skill de Claude no se dispara

Esta es la gran pregunta. Has creado tu carpeta, tienes tu archivo, has escrito un prompt estupendo... y Claude no usa la skill. ¿Qué ha pasado?

Normalmente, el problema está en una descripción demasiado vaga.

Imagina una skill llamada resumen-pr, pero con una descripción como esta:

description: Ayúdame con el código.

Eso no le dice prácticamente nada a Claude. Puede haber una pull request, un error de compilación, una duda sobre arquitectura o una petición para crear una función nueva. La descripción no identifica el caso de uso.

En cambio, una descripción como esta sí contiene una señal muy clara:

description: Resume una pull request, explica qué cambia, por qué y qué revisar con especial cuidado. Úsala al revisar un diff o antes de aprobar una PR.

Ahora, si escribes algo como “quiero revisar una pull request de mi proyecto”, Claude tiene suficiente contexto para saber que esa skill es relevante.

Las dos formas de activar una skill son:

• Por nombre: escribiendo /nombre-de-la-skill.
• Por contexto: describiendo lo que quieres hacer y dejando que Claude seleccione la habilidad adecuada.

La segunda es la que hace que el sistema resulte realmente cómodo, pero depende por completo de que el nombre y, sobre todo, la descripción estén bien escritos.

Deja que Claude Code cree la skill contigo

Escribir una skill a mano es la mejor forma de entender cómo funciona. Pero una vez que pillas el concepto, no tienes por qué construirlas todas desde cero.

Puedes pedirle a Claude Code que cree la habilidad, pero hay una frase que marca una diferencia enorme: “Pregúntame lo que necesites antes de crearla”.

Por ejemplo, podrías pedirle algo así:

Quiero crear una skill que revise mis commits antes de hacer push y me avise si el mensaje no sigue el formato estándar de mi equipo: feat, fix o chore, seguido de una descripción corta en imperativo. Pregúntame lo que necesites antes de crear la skill.

Claude puede preguntarte si quieres que se active manualmente, de forma automática o de ambas maneras. También puede pedirte que aclares si debe revisar solo el último commit, todos los commits sin enviar o únicamente los que todavía no han llegado a producción.

Y eso es exactamente lo que queremos. La IA puede ayudarte a redactar y estructurar, pero quien conoce el proceso real del equipo eres tú. Una skill mediocre asume cosas. Una skill buena pregunta, concreta y resuelve un problema de verdad.

Si quieres ir más allá de los prompts sueltos y construir sistemas de trabajo con agentes, herramientas y automatizaciones reales, tienes la ruta De Vibe Coder a Ingeniero Agéntico, diseñada precisamente para pasar de pedir tareas aisladas a diseñar flujos completos con IA.

Cuando una skill necesita ejecutar scripts

No todas las tareas se resuelven escribiendo texto. Algunas necesitan comprobar archivos, lanzar comandos, transformar datos, descargar recursos o ejecutar lógica determinista. Para eso, una skill puede incluir una carpeta llamada scripts.

.claude/skills/mi-skill/ ├── SKILL.md └── scripts/     ├── revisar_commits.py     └── validar_formato.sh

Ahí puedes guardar scripts de Python, Bash u otros lenguajes que Claude ejecute como parte del proceso. También puedes usar el campo allowed-tools en el front matter para limitar qué herramientas puede utilizar la skill.

Aquí está una de las diferencias más potentes:

• Una skill de prompt ayuda a razonar, redactar, resumir o tomar decisiones.
• Una skill de proceso combina instrucciones con pasos deterministas, scripts y herramientas controladas.

Y no, no necesitas saber escribir todos esos scripts desde cero. Claude Code también puede ayudarte a crearlos, explicarlos y adaptarlos al flujo que necesitas.

Un ejemplo real: convertir una idea en un paquete de vídeo

Una skill puede llegar bastante más lejos que resumir una pull request. Por ejemplo, una habilidad de producción de contenido puede recibir una URL de YouTube o una simple idea de vídeo.

Si recibe una URL, puede consultar el contenido disponible, extraer la idea y desarrollarla. Si recibe una idea inicial, puede estructurarla desde cero. Después genera la ideación, prepara el guion, se detiene en un punto de aprobación y, solo cuando recibe el visto bueno, continúa con el prompter, las diapositivas y los metadatos necesarios para publicar.

Eso es una skill resolviendo un problema real de negocio. No una demo de cartón piedra, sino un proceso repetible, con puntos de control y resultados útiles.

Comparte skills con tu equipo usando Git

Si una skill está dentro de .claude/skills, compartirla es aburridamente sencillo, que es justo como deberían ser las cosas que funcionan bien.

1. Haces commit de la carpeta de la skill.
2. Subes los cambios al repositorio.
3. El resto del equipo hace git pull.
4. Todo el mundo utiliza la misma versión de la habilidad.

No hace falta copiar archivos por correo, usar carpetas compartidas ni mantener versiones desincronizadas. Además, Git te da historial: puedes saber quién cambió una skill, cuándo lo hizo y por qué. Si alguien la empeora, la reviertes y listo.

Las skills son archivos de texto. Trátalas igual que tratas el código: con control de versiones, revisión y mejora continua.

Tu siguiente paso

Abre uno de tus proyectos y piensa en la tarea que más repites esta semana. No intentes crear una megaskill que haga absolutamente todo. Empieza con algo pequeño, concreto y fácil de comprobar.

Puede ser revisar mensajes de commit, preparar una pull request, validar una estructura de carpetas, resumir cambios, generar documentación o seguir una convención de nombres. Crea la carpeta, escribe un SKILL.md, define una descripción precisa y prueba si Claude la detecta cuando debe.

Cuando entiendes que una skill es una herramienta especializada, en lugar de un prompt gigantesco metido en cualquier chat, cambia por completo la forma de trabajar con Claude Code. Y esto solo es el principio: planificación, archivos CLAUDE.md, hooks, servidores MCP, subagentes y pipelines autónomos son el siguiente nivel. Para conocer el mapa completo, tienes este recorrido por todos los niveles de Claude Code.