Claude Code · SKILL.md · Automatización

Claude Code Skills: qué son, cómo crearlos y usar SKILL.md

Los Claude Code Skills permiten convertir instrucciones, checklists, conocimiento especializado y procedimientos repetitivos en capacidades reutilizables. Cada Skill puede incluir un archivo SKILL.md, documentación adicional, scripts, argumentos, herramientas autorizadas y reglas para decidir cuándo Claude debe cargarlo automáticamente.

Crear un Skill Ver ejemplos
SKILL.md .claude/skills Scripts Subagentes
Respuesta rápida

¿Qué son los Skills de Claude Code?

Un Skill es una capacidad reutilizable definida mediante un archivo SKILL.md. Claude Code puede cargar el Skill automáticamente cuando su descripción coincide con la tarea o puedes ejecutarlo manualmente con /nombre-del-skill. Para un Skill de proyecto se utiliza normalmente .claude/skills/nombre/SKILL.md, mientras que los Skills personales se guardan en ~/.claude/skills/. A diferencia de CLAUDE.md, el contenido completo del Skill solo entra al contexto cuando se utiliza.

Reutilización

Qué puede contener un Claude Code Skill

Un Skill puede ser mucho más que un prompt guardado.

DOC

Instrucciones

Procedimientos, reglas, checklists y conocimiento especializado.

REF

Referencias

Documentación extensa cargada únicamente cuando realmente sea necesaria.

ARG

Argumentos

Recibe nombres, archivos, entornos y otros parámetros al ejecutarlo.

CLI

Comandos

Puede incorporar contexto generado mediante comandos de terminal.

SCRIPT

Scripts

Python, Bash, PowerShell u otras herramientas auxiliares.

AGENT

Subagentes

Un Skill puede ejecutarse en un contexto aislado.

Publicidad
Cómo funcionan

Claude descubre el Skill y lo carga cuando lo necesita

El objetivo es mantener el contexto ligero hasta que una capacidad sea realmente relevante.

01 · DISCOVER

Claude conoce el Skill

La descripción informa qué hace y cuándo debería utilizarse.

02 · LOAD

Carga SKILL.md

El contenido completo entra al contexto únicamente cuando se invoca.

03 · EXECUTE

Ejecuta el procedimiento

Claude aplica las instrucciones, herramientas y recursos definidos.

Publicidad
Diferencias

Claude Code Skills vs CLAUDE.md

Ambos proporcionan instrucciones a Claude, pero sirven para necesidades diferentes.

Aspecto CLAUDE.md Skill
Reglas generales Ideal Posible
Procedimientos largos No recomendado Ideal
Carga constante Sí No
Carga bajo demanda No Sí
Scripts auxiliares No es su función Sí
Invocación con /comando No Sí
Argumentos No Sí
Regla sencilla

Si Claude debe recordarlo prácticamente todo el tiempo, colócalo en CLAUDE.md. Si es un procedimiento que solo necesitas en determinadas tareas, conviértelo en Skill.

Publicidad
Ubicación

Dónde guardar los Skills de Claude Code

La ubicación determina en qué proyectos estará disponible cada Skill.

Tipo Ruta Disponible en
Personal ~/.claude/skills/nombre/SKILL.md Todos tus proyectos locales
Proyecto .claude/skills/nombre/SKILL.md Ese repositorio
Nested subdir/.claude/skills/nombre/SKILL.md Área específica del proyecto
Plugin plugin/skills/nombre/SKILL.md Donde esté habilitado el plugin
Enterprise Directorio administrado Usuarios de la organización
Equipo

Skills compartidos dentro de un proyecto

Si una capacidad pertenece al repositorio, guárdala dentro del propio proyecto. 

mi-proyecto/
├── .claude/
│   └── skills/
│       ├── security-review/
│       │   └── SKILL.md
│       ├── create-endpoint/
│       │   └── SKILL.md
│       └── deploy-staging/
│           └── SKILL.md
├── src/
└── tests/
Puedes versionarlos con Git

Al incluir .claude/skills/ en el repositorio, todo el equipo puede utilizar los mismos workflows.

Primer Skill

Cómo crear un Claude Code Skill

La estructura mínima requiere un directorio y un archivo llamado exactamente SKILL.md.

Paso 1

Crear el directorio

mkdir -p .claude/skills/security-review
Paso 2

Crear SKILL.md

---
name: security-review
description: Revisa cambios de código buscando vulnerabilidades, validación insuficiente, problemas de autorización y exposición de secretos.
---

# Security Review

Analiza los cambios relacionados con seguridad.

Comprueba:

- autenticación
- autorización
- validación de inputs
- sanitización
- escaping
- SQL injection
- XSS
- CSRF
- exposición de secretos
- permisos de archivos
- llamadas a APIs externas

Devuelve primero los problemas críticos.

Incluye archivo y ubicación para cada hallazgo.

No modifiques el código salvo que el usuario lo solicite.
YAML

Qué es el frontmatter de SKILL.md

La cabecera YAML controla cómo Claude Code descubre y ejecuta el Skill. 

---
name: my-skill
description: Describe qué hace el Skill y cuándo debe usarse
disable-model-invocation: false
user-invocable: true
allowed-tools: Read Grep
---
La primera línea debe ser —

Claude Code solo interpreta la cabecera como frontmatter cuando el archivo comienza directamente con los delimitadores YAML.

Configuración

Campos importantes de un Skill

Campo Función
name Nombre visible del Skill
description Explica qué hace y cuándo utilizarlo
when_to_use Añade contexto sobre cuándo debería activarse
argument-hint Muestra qué argumentos espera
arguments Define argumentos posicionales con nombre
disable-model-invocation Impide que Claude lo ejecute automáticamente
user-invocable Controla si aparece como comando para el usuario
allowed-tools Preautoriza herramientas durante la invocación
context Puede ejecutar el Skill en contexto aislado
agent Selecciona el subagente que lo ejecutará
Activación

La descripción determina cuándo Claude descubre el Skill

description es uno de los campos más importantes.

Débil

“Ayuda con código”

Es demasiado genérica. Claude no sabe qué tareas deberían activar el Skill.

Mejor

Describe tarea + contexto

Explica claramente qué hace y qué solicitudes deberían utilizarlo. 

---
description: Revisa código WordPress buscando problemas de seguridad. Usa este Skill cuando el usuario solicite revisar plugins, themes, AJAX, REST API, formularios, nonces, capabilities o consultas SQL de WordPress.
---
Invocación

Skills automáticos vs Skills manuales

Configuración Tú puedes usarlo Claude puede usarlo
Predeterminado Sí Sí
disable-model-invocation: true Sí No
user-invocable: false No Sí
Deploy debería ser manual

Acciones con efectos importantes como desplegar producción, enviar mensajes o crear releases deberían considerar disable-model-invocation: true.

Control

Ejemplo de Skill que solo puede ejecutar el usuario

---
name: deploy
description: Despliega la aplicación al entorno indicado
disable-model-invocation: true
argument-hint: "[staging|production]"
---

Despliega $ARGUMENTS.

Antes del despliegue:

1. revisa git status
2. ejecuta los tests
3. ejecuta lint
4. ejecuta build
5. detente si algo falla

Después:

1. realiza el despliegue
2. verifica la aplicación
3. informa la versión desplegada
4. resume cualquier problema encontrado
Ejecutar

Invocación manual

/deploy staging
Publicidad
Parámetros

Pasar argumentos a un Skill

Los Skills pueden reutilizar la misma lógica con diferentes entradas.

$ARGUMENTS

Obtener todos los argumentos

---
name: explain
description: Explica un componente del proyecto
argument-hint: "[archivo o componente]"
---

Investiga y explica:

$ARGUMENTS

Incluye:
- responsabilidad
- dependencias
- entradas
- salidas
- posibles riesgos
Ejecutar 
/explain src/auth/AuthService.php
Argumentos posicionales

Utilizar $0, $1 y $2

---
name: migrate-component
description: Migra un componente entre tecnologías
argument-hint: "[componente] [origen] [destino]"
---

Migra el componente $0
desde $1
hacia $2.

Mantén:
- comportamiento actual
- tests existentes
- compatibilidad externa
Ejecutar 
/migrate-component SearchBar JavaScript TypeScript
Recursos

Un Skill puede contener varios archivos

No necesitas introducir toda la documentación dentro de SKILL.md. 

security-review/
├── SKILL.md
├── checklist.md
├── wordpress-security.md
├── examples.md
└── scripts/
    └── scan.php
Mantén SKILL.md como índice

El Skill principal puede explicar qué recursos existen y cuándo Claude debería consultarlos. 

## Recursos adicionales

- Para la checklist general consulta [checklist.md](checklist.md)
- Para WordPress consulta [wordpress-security.md](wordpress-security.md)
- Para ejemplos de vulnerabilidades consulta [examples.md](examples.md)
Tamaño

Cuánto debería medir SKILL.md

Recomendación

Mantén SKILL.md por debajo de unas 500 líneas

Para documentación extensa, especificaciones, ejemplos o referencias, utiliza archivos auxiliares en el mismo directorio.

El contenido cargado permanece en contexto

Cuando un Skill es invocado, su contenido renderizado permanece disponible durante los siguientes turnos de la conversación. Por eso conviene mantenerlo conciso.

Contexto dinámico

Inyectar datos actuales mediante comandos

Un Skill puede ejecutar un comando antes de enviarse a Claude.

!`command`

Ejemplo con Git

---
name: review-changes
description: Revisa los cambios actuales de Git y detecta riesgos
---

## Cambios actuales

!`git diff HEAD`

## Estado

!`git status --short`

## Instrucciones

Revisa los cambios anteriores.

Busca:
- bugs
- cambios accidentales
- seguridad
- falta de tests
- código muerto
- valores hardcoded
Claude recibe la salida, no solo el comando

Claude Code ejecuta primero la instrucción y reemplaza el marcador por la salida real.

Windows

Skills con PowerShell

Los Skills también pueden utilizar PowerShell cuando el entorno lo soporta. 

---
name: windows-status
description: Analiza información del entorno Windows
shell: powershell
---

## Git

!`git status --short`

## Node

!`node --version`

## PHP

!`php --version`

Analiza el entorno anterior
y señala posibles incompatibilidades.
Herramientas

Preautorizar herramientas con allowed-tools

Un Skill puede autorizar determinadas herramientas durante el turno en que se ejecuta. 

---
name: git-summary
description: Resume el estado actual del repositorio
allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)
  - Bash(git log *)
---

Revisa el repositorio
y resume los cambios recientes.
El permiso es temporal

allowed-tools se aplica al turno que invoca el Skill. Al enviar el siguiente mensaje, esa concesión desaparece.

Revisa Skills de terceros

Un Skill puede concederse herramientas, por lo que conviene revisar su frontmatter antes de utilizar Skills descargados o incluidos en repositorios ajenos.

Publicidad
Contexto aislado

Ejecutar un Skill dentro de un subagente

Algunas tareas generan demasiado contexto para ejecutarse en la conversación principal. 

---
name: deep-research
description: Investiga profundamente una parte del codebase
context: fork
agent: Explore
---

Investiga $ARGUMENTS.

1. encuentra los archivos relevantes
2. analiza el código
3. sigue las dependencias
4. identifica riesgos
5. devuelve conclusiones con referencias concretas
context: fork

Crea un contexto separado, el subagente realiza el trabajo y devuelve un resumen a la conversación principal.

Claude Code Subagents →
Diferencias

Skill vs subagente

Aspecto Skill Subagente
Objetivo Procedimiento reutilizable Delegar trabajo
Contexto propio Opcional Sí
Comando /nombre Sí No directamente
Autoactivación Sí Claude decide delegar
Archivos auxiliares Sí No es su función principal
Pueden combinarse Sí Sí
Incluidos

Claude Code también incluye Skills propios

No todos los Skills tienen que ser creados manualmente.

/code-review

Revisión de código

Skill incluido para analizar cambios de código.

/debug

Debugging

Ayuda a investigar errores y comportamiento inesperado.

/verify

Verificación

Puede construir y ejecutar la aplicación para comprobar cambios.

/run

Ejecutar aplicación

Intenta iniciar y utilizar el proyecto en ejecución.

/doctor

Diagnóstico

Analiza la instalación y configuración de Claude Code.

/claude-api

Claude API

Skill especializado en tareas relacionadas con la API de Anthropic.

Migración

Los custom commands ahora forman parte de Skills

Claude Code mantiene compatibilidad con el formato anterior.

Formato Ejemplo Resultado
Skill actual .claude/skills/deploy/SKILL.md /deploy
Formato anterior .claude/commands/deploy.md /deploy
Para nuevos workflows utiliza Skills

Los archivos de .claude/commands/ continúan funcionando, pero Skills admiten además directorios, recursos auxiliares y funciones avanzadas.

WordPress

Ejemplo de Skill para revisar plugins WordPress

Un procedimiento especializado en WordPress es un excelente candidato para Skill. 

---
name: wordpress-review
description: Revisa plugins y themes WordPress. Úsalo para auditorías de PHP, AJAX, REST API, WooCommerce, seguridad y calidad de código WordPress.
---

# WordPress Review

Investiga el proyecto antes de emitir conclusiones.

## Seguridad

Comprueba:

- sanitización de inputs
- escaping de outputs
- nonces
- capabilities
- validación de usuarios
- SQL preparado
- AJAX
- REST permissions_callback
- subida de archivos
- exposición de secretos

## WordPress

Comprueba:

- hooks
- filtros
- acciones
- uso de APIs del core
- consultas con $wpdb
- compatibilidad
- prefijos
- activación y desactivación

## WooCommerce

Cuando corresponda revisa:

- endpoints
- My Account
- órdenes
- roles
- checkout
- datos de clientes

## Resultado

Clasifica hallazgos:

1. crítico
2. alto
3. medio
4. bajo

Para cada problema incluye:

- archivo
- causa
- impacto
- recomendación

No modifiques código hasta que el usuario lo solicite.
Ejecutar 
/wordpress-review
Claude Code para WordPress →
Workflow

Ejemplo de Skill para preparar releases

---
name: prepare-release
description: Prepara una release sin publicarla
disable-model-invocation: true
allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)
  - Bash(git log *)
---

Prepara la release $ARGUMENTS.

1. comprueba git status
2. revisa cambios desde la última versión
3. identifica breaking changes
4. revisa tests
5. revisa documentación
6. genera release notes
7. propone versión semántica

No:
- hagas push
- publiques releases
- cambies tags
- despliegues producción
APIs

Ejemplo de Skill para crear endpoints

---
name: create-endpoint
description: Crea endpoints siguiendo las convenciones API del proyecto
argument-hint: "[recurso]"
---

Crea el endpoint para:

$ARGUMENTS

Antes de programar:

1. encuentra endpoints similares
2. identifica arquitectura actual
3. revisa validación
4. revisa autenticación
5. revisa formato de errores

Durante la implementación:

- reutiliza patrones existentes
- valida inputs
- verifica autorización
- añade tests
- documenta el endpoint

Al terminar:

- ejecuta tests
- ejecuta lint
- resume los archivos modificados
Publicidad
Distribución

Skills dentro de Claude Code Plugins

Si quieres distribuir varios Skills junto con agents, Hooks o servidores MCP, un Plugin puede ser más apropiado. 

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── review/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md
├── agents/
├── hooks/
└── .mcp.json
Los Skills de Plugins están namespaced

Un Skill llamado review dentro del plugin my-plugin puede aparecer como /my-plugin:review.

Claude Code Plugins →
Administración

Ver los Skills disponibles

/skills

Abrir el administrador

/skills
Puedes controlar visibilidad

El administrador permite revisar qué Skills están disponibles y ajustar cómo aparecen en la sesión.

Desarrollo

Editar Skills sin reiniciar Claude Code

Claude Code observa normalmente los directorios de Skills existentes.

Hot reload

Edita SKILL.md durante la sesión

Los cambios realizados sobre Skills personales o del proyecto pueden detectarse durante la sesión sin reiniciar Claude Code.

Excepción

Si creas por primera vez el directorio principal de Skills después de iniciar la sesión, puede ser necesario reiniciar Claude Code para que empiece a observarlo.

Calidad

Cómo saber si un Skill realmente funciona

Que Claude active un Skill no significa automáticamente que esté bien diseñado.

01

Prueba solicitudes donde sí debería activarse.

02

Prueba solicitudes donde no debería activarse.

03

Compara el resultado con el Skill activado y desactivado.

04

Ejecuta las pruebas desde sesiones nuevas para evitar contexto residual.

05

Ajusta especialmente description si se activa demasiado o demasiado poco.

Evaluación avanzada

Skill Creator para probar Skills

Anthropic dispone de un plugin oficial orientado a evaluar y mejorar Skills.

Plugin

Instalar Skill Creator

/plugin install skill-creator@claude-plugins-official
Qué puede medir

Puede ejecutar casos aislados, evaluar resultados, comparar con y sin Skill, medir tokens y ayudar a optimizar la descripción.

Contexto

Demasiados Skills también tienen un coste

El contenido completo no se carga siempre, pero Claude necesita conocer las descripciones de los Skills disponibles.

/skill-doctor

Encontrar Skills poco utilizados

/skill-doctor
Más no siempre es mejor

Desactiva Skills que nunca utilizas o cuya descripción ocupa contexto sin aportar valor.

Buenas prácticas

Cómo diseñar buenos Claude Code Skills

01

Define una responsabilidad clara por Skill.

02

Escribe una description específica sobre cuándo utilizarlo.

03

Mantén SKILL.md conciso y mueve referencias extensas a otros archivos.

04

Utiliza argumentos cuando el procedimiento deba adaptarse.

05

Haz manuales los Skills con efectos importantes.

06

Limita allowed-tools a lo realmente necesario.

07

Ejecuta tareas muy grandes en un subagente.

08

Versiona los Skills compartidos junto al proyecto.

Decisión

Cuándo convertir un procedimiento en Skill

Repetición Pegas el mismo prompt constantemente
Skill
Procedimiento Tienes una checklist de varios pasos
Skill
Conocimiento Documentación especializada usada ocasionalmente
Skill
Regla global Debe aplicarse siempre
CLAUDE.md
Delegación Necesitas contexto y herramientas separados
Subagent
Distribución Quieres agrupar Skills + Hooks + MCP
Plugin
Fuente oficial

Documentación oficial de Claude Code Skills

Los Skills están evolucionando rápidamente, por lo que conviene revisar la documentación para nuevas opciones de frontmatter, agentes y distribución.

Anthropic

Plugins

Distribución de Skills junto con agents, Hooks y MCP.

Ver Plugins →
Publicidad
Cluster Claude Code

Guías relacionadas

Continúa con subagentes, MCP, Plugins, Hooks y automatización.

Publicidad
Preguntas frecuentes

FAQ sobre Claude Code Skills

Respuestas sobre SKILL.md, rutas, activación, argumentos, scripts, herramientas y distribución.

Un Skill es una capacidad reutilizable definida mediante un archivo SKILL.md. Puede contener instrucciones, procedimientos, recursos, scripts y configuración.

Los Skills personales se guardan normalmente en ~/.claude/skills/. Los Skills compartidos de un proyecto se guardan en .claude/skills/.

SKILL.md es el archivo principal de un Skill. Contiene frontmatter YAML con la configuración y contenido Markdown con las instrucciones que Claude debe seguir.

Sí. De forma predeterminada Claude conoce las descripciones de los Skills disponibles y puede cargar uno automáticamente cuando resulte relevante.

Utiliza una barra seguida del nombre del directorio del Skill. Por ejemplo, un Skill ubicado en .claude/skills/review/SKILL.md puede ejecutarse mediante /review.

Añade disable-model-invocation: true al frontmatter. El Skill seguirá disponible para que tú lo invoques manualmente.

CLAUDE.md contiene instrucciones generales cargadas como contexto del proyecto. Un Skill se utiliza para capacidades o procedimientos concretos y su contenido completo se carga únicamente cuando se invoca.

Sí. El directorio puede incluir documentación, ejemplos, referencias y scripts auxiliares. SKILL.md debe indicar cuándo utilizar esos recursos.

Sí. Claude Code admite inyección de contexto mediante comandos utilizando la sintaxis de shell del Skill, sujeto a configuración y permisos.

Sí. Un Skill puede utilizar context: fork y seleccionar un agente como Explore, Plan, general-purpose o un subagente personalizado.

Publicidad
Siguiente guía

Delega tareas con Claude Code Subagents

Ya puedes convertir procedimientos repetitivos en Skills reutilizables. El siguiente paso es aprender a crear agentes especializados con su propio contexto, modelo, instrucciones, herramientas y permisos.

Claude Code Subagents →
Carrito de compra
Scroll al inicio