Skills en Claude Code: qué son, cómo crearlas y cómo usarlas

En esta guía

1. ¿Qué son las Skills?
2. Estructura de archivos
3. Frontmatter y opciones
4. Variables y contexto dinámico
5. Cómo invocarlas
6. Skills globales vs. de proyecto
7. Buenas prácticas y skill de ejemplo

1. ¿Qué son las Skills?

Una Skill es un archivo SKILL.md que contiene una plantilla de prompt. Cuando la invocás, Claude Code inyecta ese contenido en el contexto de la conversación y Claude lo ejecuta como instrucción.

La diferencia clave frente a CLAUDE.md es el lazy loading: el contenido de CLAUDE.md se carga automáticamente en cada sesión; el de una Skill solo se carga cuando vos la invocás (o cuando Claude detecta que es relevante). Eso las hace muy baratas: no gastan tokens de contexto hasta que las necesitás.

"Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."
— Anthropic Docs

En la práctica sirven para estandarizar tareas repetitivas: revisiones de PR, deploys, auditorías de seguridad, migraciones, generación de documentación, etc.

2. Estructura de archivos

Cada Skill vive en su propia carpeta con un único archivo SKILL.md. El nombre de la carpeta es el comando que escribís después del /. El campo name del frontmatter solo cambia la etiqueta en /help, no el comando.

.claude/
└── skills/
    ├── revisar-pr/
    │   └── SKILL.md       →  /revisar-pr
    ├── deploy-staging/
    │   └── SKILL.md       →  /deploy-staging
    └── audit-seguridad/
        └── SKILL.md       →  /audit-seguridad

Para skills personales (disponibles en todos tus proyectos):

~/.claude/
└── skills/
    └── mi-skill-global/
        └── SKILL.md       →  /mi-skill-global

Formato legacy (soportado pero desaconsejado):

.claude/commands/revisar-pr.md   →  /revisar-pr

Si una Skill y un comando legacy comparten nombre, la Skill tiene prioridad.

3. Frontmatter y opciones disponibles

La cabecera YAML entre --- es opcional pero te da control fino sobre el comportamiento de la Skill.

---
name: "Revisar PR"
description: "Analiza el diff del PR buscando bugs y oportunidades de mejora"
allowed-tools: Bash, Read, Grep
model: claude-opus-4-8
argument-hint: "[número de PR]"
---

Revisá el PR #$ARGUMENTS buscando...

Campo	Qué hace
name	Etiqueta visible en /help. No cambia el comando que escribís.
description	Descripción corta visible en /help.
allowed-tools	Herramientas que Claude puede usar durante esta Skill (Bash, Read, Grep, etc.).
model	Modelo específico para esta Skill. Útil para forzar Opus en tareas complejas o Haiku en las simples.
argument-hint	Sugerencia que aparece como placeholder mientras escribís el comando.

4. Variables y contexto dinámico

Variables de sustitución

Se reemplazan automáticamente al invocar la Skill:

Variable	Qué contiene
$ARGUMENTS	Todo el texto escrito después del comando.
$0, $1, $2	Argumentos posicionales separados por espacio (base 0).
$nombre	Argumento nombrado declarado en frontmatter.
${CLAUDE_SESSION_ID}	ID único de la sesión actual.
${CLAUDE_EFFORT}	Nivel de esfuerzo configurado en la sesión.
${CLAUDE_SKILL_DIR}	Ruta absoluta al directorio de la Skill.

Ejemplo: /migrate-component SearchBar React Vue resuelve $0=SearchBar, $1=React, $2=Vue.

Inyección de shell

La sintaxis !`comando` ejecuta un comando de shell antes de enviar la Skill a Claude. El output reemplaza el placeholder. Ideal para inyectar contexto del repo sin escribirlo a mano:

---
description: "Evalúa si la rama está lista para merge"
---

Estado actual del repositorio:
- Branch: !`git branch --show-current`
- Último commit: !`git log -1 --oneline`
- Archivos cambiados: !`git status --short`

Con base en este estado, evaluá si la rama está lista para hacer merge
y qué falta antes de hacerlo.

Inclusión de archivos

Usá @filename para incluir el contenido de un archivo directamente en la Skill:

Tenés este package.json como referencia:
@package.json

Identificá las dependencias obsoletas o con vulnerabilidades conocidas
y proponé actualizaciones con justificación.

5. Cómo invocarlas

Escribís el nombre de la carpeta con / adelante en el chat de Claude Code, seguido de los argumentos que necesite:

/revisar-pr 142
/deploy-staging
/migrate-component UserCard React Vue
/audit-seguridad src/api/

Para listar todas las Skills disponibles con su descripción:

/help

Las Skills de plugins usan un namespace compuesto:

/nombre-plugin:nombre-skill

Invocación automática: Claude puede activar una Skill por su cuenta si detecta que es relevante para la tarea que estás describiendo, incluso sin que vos la menciones explícitamente.

6. Skills globales vs. de proyecto

Ubicación	Alcance	Cuándo usarla
~/.claude/skills/<nombre>/SKILL.md	Todos tus proyectos	Workflows personales universales: revisar PRs, debugging, etc.
.claude/skills/<nombre>/SKILL.md	Solo este proyecto	Procesos específicos: deploys, migraciones, convenciones del equipo.
Plugin (plugin:skill)	Según el plugin	Skills compartidas en equipo via plugins instalados.

Precedencia cuando hay conflicto de nombres:

Enterprise  →  Personal (~/.claude)  →  Proyecto (.claude)

Las Skills de plugins nunca colisionan porque usan el namespace plugin:skill. Si trabajás en equipo, commitá .claude/skills/ en el repo para que todos tengan los mismos comandos.

7. Buenas prácticas y Skill de ejemplo

Skills vs CLAUDE.md vs Rules

• CLAUDE.md → instrucciones que siempre aplican: estilo de código, stack del proyecto, convenciones de commits.
• Rules → restricciones por tipo de archivo (se cargan cuando abrís archivos que coinciden).
• Skills → tareas que ejecutás cuando querés: revisiones, deploys, auditorías. No consumen contexto el resto del tiempo.

Tips rápidos

• Commitá .claude/skills/ en el repo para que todo el equipo tenga los mismos comandos.
• Usá allowed-tools para limitar permisos en Skills delicadas (ej. solo lectura).
• Asigná model: claude-haiku-4-5 en Skills simples para reducir costos.
• Nombrá las carpetas con kebab-case descriptivo: audit-seguridad, no s1.
• Usá la inyección de shell para dar contexto del estado del repo automáticamente.

Ejemplo completo: Skill de auditoría de seguridad

---
name: "Audit de Seguridad"
description: "Revisa código buscando vulnerabilidades OWASP Top 10"
allowed-tools: Read, Grep, Bash
model: claude-opus-4-8
argument-hint: "[archivo o directorio, default: src/]"
---

Realizá un audit de seguridad enfocado en OWASP Top 10.

Contexto del proyecto:
- Stack: !`cat package.json | grep -E '"(next|express|fastify|hono)"' | head -5`
- Issues de dependencias: !`npm audit --json 2>/dev/null | head -30`

Directorio a revisar: $ARGUMENTS

Buscá específicamente:
1. Inyección (SQL, NoSQL, comandos de shell)
2. XSS y falta de sanitización en inputs
3. Autenticación débil o sesiones mal manejadas
4. Datos sensibles expuestos en logs o respuestas de API
5. Dependencias con CVEs conocidos

Por cada hallazgo: archivo, número de línea, severidad (alta/media/baja) y cómo corregirlo.