- Los skills son archivos Markdown (.md) sin código: solo instrucciones en lenguaje natural que Claude Code sigue al recibir el slash command correspondiente.
- Se almacenan en
~/.claude/skills/(globales, disponibles en todos los proyectos) o en.claude/skills/dentro del repositorio (específicos del proyecto). - Se invocan con
/nombre-del-skilldurante cualquier sesión de Claude Code, sin configuración adicional. - Pueden incluir procedimientos paso a paso, plantillas de código, reglas de validación, referencias a otros archivos del proyecto y condiciones de fallo.
- Son distintos de CLAUDE.md (instrucciones permanentes que se cargan siempre) y de los hooks (scripts que se ejecutan automáticamente en eventos del ciclo del agente).
¿Qué son los skills de Claude Code y para qué sirven?
Cuando trabajas con Claude Code de forma continua, ciertos procedimientos se repiten sesión tras sesión: validar que una fase del proyecto ha cumplido todos sus requisitos antes de avanzar, registrar una decisión arquitectónica con su razonamiento, generar un resumen del estado actual del repositorio o ejecutar una revisión de código según los criterios del equipo. Sin los skills, habría que describir cada uno de estos procedimientos en lenguaje natural cada vez que se necesitan, con el riesgo de omitir pasos o de que el agente interprete las instrucciones de forma ligeramente diferente en cada sesión.
Los skills resuelven exactamente ese problema. Son instrucciones reutilizables encapsuladas en un archivo Markdown que el agente carga y ejecuta en su totalidad cuando el usuario invoca el slash command correspondiente. La diferencia con un simple texto en el chat es que los skills son versionables (viven en el repositorio), compartibles con el equipo y suficientemente detallados como para incluir ramificaciones condicionales, listas de verificación, plantillas de salida y referencias a archivos externos.
Técnicamente, un skill no es más que un archivo .md colocado en la carpeta
correcta. Claude Code detecta automáticamente los archivos de esa carpeta y los expone
como slash commands disponibles durante la sesión. No se requiere código, configuración
ni registro previo. El contenido del archivo es la única fuente de verdad sobre lo que
hace el skill cuando se invoca.
La documentación oficial de skills de Anthropic está en docs.anthropic.com. Para entender el ecosistema completo de extensión de Claude Code, ver también la guía de MCP para Claude Code.
Cómo crear un skill: estructura del archivo y frontmatter
Crear un skill es tan simple como crear un archivo Markdown en la carpeta correspondiente.
La única convención obligatoria es la ubicación y el nombre del archivo: el nombre del
archivo (sin la extensión .md) será el nombre del slash command con el que
se invocará el skill.
Estructura básica de un archivo SKILL.md
Un skill puede ser tan simple como una lista de pasos en Markdown o tan complejo como un procedimiento con múltiples secciones, condiciones de fallo y referencias a otros archivos. La estructura recomendada es la siguiente:
---
name: nombre-del-skill
description: Descripcion breve de lo que hace el skill (aparece en /help).
trigger: Condiciones opcionales que activan el skill automaticamente.
---
# Nombre del skill
Descripcion extendida del objetivo del skill.
## Cuando usar este skill
Indicar en que situaciones es apropiado invocar este skill.
## Procedimiento
1. Primer paso del procedimiento.
2. Segundo paso, con las instrucciones necesarias.
3. Tercer paso. Si ocurre X, seguir el subapartado de error.
### Si el paso 2 falla
Instrucciones especificas para el caso de fallo.
## Formato de salida esperado
Indicar el formato en que el agente debe presentar el resultado.
## Referencias
- Plantilla: _shared/templates/mi-plantilla.md
- Documentacion: docs/mi-proceso.mdEl frontmatter YAML
El frontmatter (el bloque delimitado por --- al inicio del archivo) es
opcional pero recomendable. Los campos que reconoce Claude Code son:
| Campo | Obligatorio | Descripción |
|---|---|---|
name |
No | Nombre legible del skill. Si se omite, se usa el nombre del archivo. |
description |
No | Descripción breve que aparece cuando el usuario ejecuta /help en la sesión. |
trigger |
No | Condiciones de activación automática. Permite que el agente invoque el skill sin que el usuario lo solicite explícitamente. |
El cuerpo de instrucciones
El cuerpo del skill, escrito en Markdown estándar, es lo que el agente lee y ejecuta. Puede contener cualquier combinación de los siguientes elementos:
- Procedimientos paso a paso — listas numeradas que el agente sigue en orden.
- Condiciones de ramificación — instrucciones del tipo "si ocurre X, haz Y; de lo contrario, haz Z".
- Listas de verificación — checklists con
- [ ]que el agente evalúa antes de declarar el skill completado. - Plantillas de salida — bloques de código o Markdown que el agente debe generar como resultado.
- Referencias a archivos — rutas a plantillas, documentación interna u otros skills que el agente leerá como contexto adicional.
- Condiciones de fallo irrevocable — ítems que nunca deben considerarse superados aunque el usuario lo solicite.
Skills globales vs. skills de proyecto
Claude Code distingue dos ámbitos de skills según dónde se almacenan. Cada ámbito tiene su caso de uso óptimo.
~/.claude/skills/
Los skills globales se almacenan en el directorio ~/.claude/skills/
del directorio home del usuario y están disponibles en todos los proyectos
sin necesidad de copiarlos ni configurarlos en cada repositorio.
Son ideales para procedimientos personales que aplican a cualquier proyecto: flujos de debugging que el desarrollador siempre sigue, comandos de productividad personal, plantillas de commit message o convenciones de código propias. No se versionan junto al proyecto, por lo que son privados por naturaleza.
Ejemplo de uso: un skill /mi-review que ejecuta
la checklist de revisión de código que el desarrollador aplica a cualquier PR,
independientemente del stack tecnológico del proyecto.
.claude/skills/
Los skills de proyecto se almacenan en .claude/skills/ dentro de
la raíz del repositorio y están disponibles únicamente en ese proyecto.
Al vivir dentro del repositorio, se versionan con Git y son compartidos por todo
el equipo que trabaje en el mismo proyecto.
Son ideales para procedimientos específicos del proyecto: gates de calidad que verifican requisitos de cada fase, flujos de despliegue propios del stack, comandos de generación de documentación o cualquier proceso que deba ser consistente entre todos los miembros del equipo.
Ejemplo de uso: un skill /gate que verifica
mecánicamente que todos los outputs de la fase actual están presentes y bien
formados antes de avanzar a la siguiente fase del proyecto.
Prioridad cuando un skill existe en ambos ámbitos
Si existe un skill con el mismo nombre en ~/.claude/skills/ y en
.claude/skills/, el skill de proyecto tiene prioridad sobre el global.
Esto permite que los equipos sobreescriban skills globales con versiones adaptadas
a las necesidades específicas del proyecto sin necesidad de modificar la configuración
personal del desarrollador.
Convención de nombres recomendada
Para mantener los skills organizados y fácilmente identificables, se recomienda
usar nombres en minúsculas separados por guiones que describan claramente la acción
que ejecuta el skill: gate.md, deploy.md,
review-pr.md, checkpoint.md, audit-seguridad.md.
Evitar nombres genéricos como helper.md o utils.md que
no describen la función específica del skill.
Ejemplos prácticos de skills de Claude Code
Los siguientes ejemplos son skills reales que ilustran los patrones de uso más habituales: validación de fases, registro de decisiones, auditoría de cumplimiento y captura del estado de sesión. Cada uno está pensado para ser usado directamente o como punto de partida para adaptarlo al flujo de trabajo del equipo.
Ejemplo 1: /gate — validador de fases del proyecto
El skill /gate verifica mecánicamente que todos los outputs obligatorios
de la fase actual de un proyecto están presentes y bien formados antes de avanzar a
la siguiente fase. Devuelve PASS, WARN o FAIL con detalle de lo que falta.
---
name: gate
description: Verifica que los outputs de la fase actual estan completos antes de avanzar.
---
# Gate de fase
Invoca este skill con /gate <N> para verificar la fase N antes de empezar la N+1.
## Procedimiento
1. Leer el documento de fases del proyecto en docs/GUIA-MAESTRA-FASES.md
para identificar los outputs obligatorios de la fase N.
2. Comprobar que cada output existe en el repositorio con el formato correcto.
3. Para cada output:
- Si existe y esta bien formado: marcar como OK.
- Si existe pero esta incompleto o vacio: marcar como WARN.
- Si no existe: marcar como FAIL.
4. Calcular el veredicto final:
- PASS: todos los outputs estan en OK.
- WARN: hay outputs en WARN pero ningun FAIL. Se puede avanzar con cautela.
- FAIL: hay al menos un output en FAIL. NO avanzar a la fase siguiente.
## Outputs que NUNCA pueden ser WARN (FAIL irrevocable)
- 5.7: superadmin sembrado en base de datos.
- 6.7: idempotencia de pagos verificada.
- 10.4: tests en verde.
- 11.9: backup previo al despliegue.
## Formato de salida
```
-- Gate fase N --
[OK] nombre-output-1
[WARN] nombre-output-2 — descripcion del problema
[FAIL] nombre-output-3 — descripcion de lo que falta
Veredicto: PASS | WARN | FAIL
```Ejemplo 2: /decide — registrador de decisiones arquitectónicas
El skill /decide captura una decisión arquitectónica o de implementación
con su razonamiento y la añade al log de decisiones del proyecto. Es útil para
mantener un historial trazable de por qué se tomó cada decisión importante.
---
name: decide
description: Registra una decision arquitectonica en .claude/decisions.md con fecha y razonamiento.
---
# Registrador de decisiones
Invoca con /decide "<titulo>" "<razonamiento>"
## Procedimiento
1. Obtener la fecha actual en formato YYYY-MM-DD.
2. Leer el archivo .claude/decisions.md del proyecto.
Si no existe, crearlo con la cabecera:
# Decisiones del proyecto
> Log append-only de decisiones arquitectonicas. No borrar entradas.
3. Añadir al final del archivo la nueva entrada con el formato:
## [FECHA] Titulo de la decision
**Razonamiento:** razonamiento proporcionado por el usuario.
**Contexto:** (opcional) contexto adicional relevante para entender la decision.
---
4. Confirmar al usuario que la decision ha sido registrada.
## Regla absoluta
Este archivo es append-only. Nunca modificar ni borrar entradas existentes.Ejemplo 3: /audit — verificador de cumplimiento del proyecto
El skill /audit revisa el estado del repositorio y verifica que cumple
con las reglas declaradas en la memoria del proyecto y en el archivo de decisiones.
Genera un informe de cumplimiento con los problemas encontrados.
---
name: audit
description: Audita el repositorio contra las reglas de CLAUDE.md y .claude/decisions.md.
---
# Auditoria de cumplimiento
## Cuando usar este skill
Usar /audit cuando quieras verificar que el proyecto sigue las convenciones
acordadas: estructura de carpetas, convenciones de nombres, patrones de codigo,
ausencia de credenciales en archivos versionados, etc.
## Procedimiento
1. Leer CLAUDE.md para extraer las reglas absolutas y convenciones del proyecto.
2. Leer .claude/decisions.md para identificar decisiones que implican reglas de implementacion.
3. Revisar la estructura del repositorio contra la estructura estandar definida en CLAUDE.md.
4. Para cada regla identificada, verificar si el repositorio la cumple.
5. Generar el informe con el siguiente formato:
## Formato de informe
```
-- Auditoria de cumplimiento --
Fecha: YYYY-MM-DD
Reglas verificadas: N
CUMPLE regla-1
INCUMPLE regla-2 — descripcion del incumplimiento
AVISO regla-3 — descripcion del aviso
Resumen: N cumple, N incumple, N avisos
```
## Prioridad de los incumplimientos
- INCUMPLE: el repositorio viola una regla declarada como absoluta.
- AVISO: el repositorio se desvía de una convencion recomendada pero no obligatoria.Ejemplo 4: /checkpoint — captura del estado de sesión
El skill /checkpoint genera un resumen estructurado del estado actual
del proyecto al cerrar la sesión, de forma que la próxima sesión pueda retomar el
trabajo desde el punto exacto donde se dejó.
---
name: checkpoint
description: Actualiza .claude/status.md y .claude/pending.md con el estado actual del proyecto.
---
# Checkpoint de sesion
## Cuando usar este skill
Invocar /checkpoint al final de cada sesion de trabajo para dejar un registro
del estado actual que permita retomar facilmente en la proxima sesion.
## Procedimiento
1. Revisar los cambios realizados durante la sesion (git diff, archivos modificados).
2. Identificar la fase actual del proyecto leyendo docs/GUIA-MAESTRA-FASES.md.
3. Actualizar el archivo .claude/status.md con el formato siguiente (sobrescribir):
```
# Estado del proyecto — YYYY-MM-DD
## Fase actual
Fase N: nombre de la fase
## Ultimo trabajo realizado
- Descripcion concisa de lo que se hizo en esta sesion.
## Proximos pasos
- Siguiente accion concreta para continuar el trabajo.
## Notas para la proxima sesion
Cualquier contexto importante que no sea obvio del codigo.
```
4. Revisar .claude/pending.md y marcar como [x] las tareas completadas en la sesion.
5. Añadir al final de .claude/pending.md las nuevas tareas identificadas, si las hay.
6. Confirmar al usuario que el checkpoint ha sido guardado.
## Regla
Nunca borrar entradas de .claude/pending.md. Solo marcar como completadas ([x]).Buenas prácticas para diseñar y organizar skills
Patrones que hacen que los skills sean robustos, predecibles y fáciles de mantener a lo largo del tiempo.
Un skill, una responsabilidad
El principio de responsabilidad única aplica igualmente a los skills. Un skill debe hacer una sola cosa y hacerla bien: validar una fase, registrar una decisión o generar un checkpoint. Cuando un skill acumula demasiadas responsabilidades, su comportamiento se vuelve impredecible y difícil de depurar. Si un procedimiento requiere varios pasos independientes, considera crear un skill por cada paso y un skill "orquestador" que los invoque en orden.
Definir condiciones de éxito y de fallo explícitas
Un skill robusto describe no solo lo que hay que hacer sino también cómo sabe el agente que ha terminado correctamente y qué hacer si algo falla. Incluir siempre una sección de "formato de salida esperado" que especifique la estructura del resultado y, cuando aplique, una lista de condiciones de fallo irrevocable que el agente no puede saltarse aunque el usuario lo solicite.
Referenciar archivos en lugar de duplicar contenido
En lugar de copiar la lista de reglas del proyecto dentro de cada skill, referenciar
el archivo que las contiene (CLAUDE.md, docs/,
plantillas en _shared/templates/). Esto garantiza que los skills
siempre trabajan con la versión más actualizada de las reglas y evita
inconsistencias cuando las convenciones cambian.
Versionar los skills de proyecto con Git
Los skills de proyecto en .claude/skills/ deben estar versionados
junto al código del proyecto. Esto garantiza que todos los miembros del equipo
trabajan con la misma versión de los procedimientos y que los cambios en los
skills quedan registrados en el historial de Git con su correspondiente mensaje
de commit descriptivo.
Usar la descripción del frontmatter como documentación
El campo description del frontmatter es lo primero que el usuario
ve cuando ejecuta /help en la sesión. Debe ser una frase concisa
que responda a la pregunta "¿para qué sirve este skill?". Una buena descripción
evita que los miembros del equipo tengan que abrir el archivo para saber si
un skill hace lo que necesitan.
Probar los skills con casos reales antes de añadirlos al equipo
Antes de compartir un skill con el resto del equipo, probarlo con varios casos reales para verificar que el agente lo interpreta como se espera. Los skills ambiguos o con instrucciones contradictorias generan comportamientos impredecibles. Si el agente sistemáticamente hace algo distinto a lo esperado, revisar la redacción del procedimiento para eliminar la ambigüedad.
¿Cuándo usar skills, CLAUDE.md o hooks?
Los tres mecanismos de extensión de Claude Code sirven para controlar el comportamiento del agente, pero en momentos y contextos distintos. Elegir el mecanismo incorrecto genera redundancia, incoherencia o comportamientos inesperados.
| Característica | Skills (/comando) |
CLAUDE.md | Hooks (scripts) |
|---|---|---|---|
| Cuando se activa | Solo cuando el usuario invoca el slash command | Al inicio de cada sesión, siempre | Automáticamente en eventos del ciclo del agente |
| Formato | Archivo Markdown (.md) | Archivo Markdown (.md) | Script ejecutable (bash, Python, etc.) |
| Requiere código | No | No | Sí |
| Versionable en Git | Sí (skills de proyecto) | Sí | Sí |
| Ámbito | Global o por proyecto | Global (~/) o por proyecto | Global (~/) o por proyecto |
| Mejor para | Procedimientos bajo demanda, flujos complejos, checklists | Contexto permanente, reglas absolutas, convenciones globales | Automatización de eventos: linting, notificaciones, logging |
| Ejemplos típicos | /gate, /decide, /audit, /checkpoint, /deploy, /review | Stack tecnológico, archivos prohibidos, reglas de commit | Ejecutar linter antes de commit, enviar notificación al terminar |
Regla práctica para elegir el mecanismo correcto
Si la instrucción debe estar activa en todo momento durante cualquier
sesión, pertenece a CLAUDE.md. Si debe ejecutarse automáticamente
cuando ocurre un evento específico del ciclo del agente (antes de cada herramienta, al
finalizar, al detectar un error), usar un hook. Si es un procedimiento
complejo que el usuario o el agente invoca bajo demanda en momentos
específicos del flujo de trabajo, usar un skill.
Preguntas frecuentes sobre los skills de Claude Code
¿Qué es un skill de Claude Code?
Un skill de Claude Code es un archivo Markdown (.md) que encapsula
un conjunto de instrucciones reutilizables para el agente. Se invoca mediante un
slash command (/nombre-del-skill) durante cualquier sesión de Claude Code
y proporciona al agente procedimientos específicos, reglas de validación, plantillas
de código y convenciones de equipo. Los skills son la herramienta de extensión de
Claude Code para procedimientos bajo demanda que resultan demasiado complejos o
específicos para incluir en CLAUDE.md.
¿Dónde se guardan los skills de Claude Code?
Los skills se guardan en dos ubicaciones según su ámbito:
~/.claude/skills/— skills globales, disponibles en todos los proyectos del usuario..claude/skills/— skills de proyecto, disponibles solo en ese repositorio y versionados con Git.
El nombre del archivo (sin .md) es el nombre del slash command. Por
ejemplo, .claude/skills/gate.md se invoca con /gate.
¿Los skills de Claude Code requieren saber programar para crearlos?
No. Los skills son archivos Markdown puros: no requieren código, scripts ni configuración especial. Solo hace falta escribir las instrucciones en lenguaje natural que el agente seguirá al invocarlos. Esto los hace accesibles para cualquier miembro del equipo, incluidos los que no tienen perfil técnico. La única "programación" que requieren es pensar bien el procedimiento que el agente debe seguir.
¿Qué diferencia hay entre un skill y las instrucciones en CLAUDE.md?
La diferencia clave es cuándo se activan. CLAUDE.md contiene instrucciones permanentes que el agente carga al inicio de cada sesión y que están activas todo el tiempo: convenciones del proyecto, reglas absolutas, stack tecnológico. Los skills son instrucciones especializadas que el agente carga únicamente cuando el usuario invoca el slash command correspondiente. CLAUDE.md es contexto siempre presente; los skills son procedimientos bajo demanda.
¿Pueden los skills referenciar otros archivos del proyecto?
Sí. Un skill puede incluir rutas relativas o absolutas a archivos del repositorio:
plantillas en _shared/templates/, documentación en docs/,
el propio CLAUDE.md u otros skills. Al invocar el skill, Claude Code
lee los archivos referenciados y los incorpora como contexto adicional para ejecutar
el procedimiento. Esto permite que los skills trabajen siempre con la versión
más actualizada de las reglas y evita duplicar contenido entre archivos.
¿Es posible que Claude Code invoque un skill automáticamente sin que el usuario lo solicite?
Sí. El campo trigger del frontmatter permite definir condiciones de
activación automática para un skill. Por ejemplo, un skill con
trigger: Al finalizar cada fase del proyecto puede ser invocado
automáticamente por el agente cuando detecta que se ha completado una fase sin
que el usuario lo solicite explícitamente. Esta funcionalidad permite integrar
los skills en el flujo de trabajo de forma transparente. Para automatizaciones
más complejas basadas en eventos del ciclo del agente, los
hooks son la herramienta adecuada.