¿Qué son las famosas Skills en Claude Code?

Si estás al día en tech en redes, o al menos lo intentas, habrás escuchado ya mil veces la palabras "skills", desde personas explicando qué son y como mejora su flujo de trabajo, hasta otros que venden una skill que los hizo "millonarios" (Obviamente fake).

Yo estuve abrumado por varias semanas con tanta noticia de AI, y me costó entrarle al concepto de Skills. No porque sean difíciles, de hecho se aprenden en 10 minutos, sino porque hay demasiada información regada sobre AI y poca explicación paso por paso.

Para entender AI como dev debes entender 3 cosas fundamentales:

• Agentes

• MCP

• Skills

(Estos serán links a Blogs próximamente, atento a las publicaciones)

Hoy hablaremos sobre Skills en Claude Code (pero sirven en TODOS lados, ya que ahora son un standard, y puedes usarlas en Gemini CLI, Cursor, etc)

Qué es un Skill

Un Skill es un archivo Markdown con frontmatter YAML que define un comando invocable, ya sea por el usuario (/nombre-del-skill) o por el propio modelo cuando detecta que es relevante.

La idea de un skill es encasillar un conocimiento o tarea específica en un archivo que puedes llamar en cualquier momento.

Por ejemplo, yo todas las semanas me encuentro creando tickets de Github. Estos cuentan con título, descripción, tipo, pasos para reproducir el issue, etc.

Ya tengo una estructura para crearlos, un template que sigo y relleno manualmente.

Este es un buen candidato para una skill, ya que puedo encasillar este template, junto con lo que debo hacer, y crear una skill para que un agente lo haga por mi.

La estructura mínima para un skill es esta:

// ~/.claude/skills/mi-skill/SKILL.md
---
name: mi-skill
description: Hace X cosa concreta cuando el usuario necesita Y
---

Instrucciones que Claude seguirá cuando se invoque este skill.

Eso es todo lo que necesitas para tener un slash command funcional en tu sesión.

Cómo funcionan por dentro

Cuando inicias una sesión, Claude Code escanea automáticamente los directorios de skills y carga las descripciones (no el contenido completo) en el contexto. Esto ocupa aproximadamente el 1% del context window y permite que Claude sepa qué skills existen sin consumir tokens innecesarios.

Por eso es MUY importante que la descripción que coloques en el skill sea coherente, concisa y vaya al grano. Esta descripción la escribes para que el agente sepa que, de necesitarlo, puede contar con tu skill para hacer X cosa

El flujo completo de ejecución es el siguiente:

1. Inicio de sesión (SessionStart):

• Se cargan las descripciones de todos los skills disponibles

• Las descripciones están limitadas a 250 caracteres (se truncan si son más largas)

• El contenido completo del skill NO se carga aún

2. Invocación por usuario (/nombre-del-skill argumentos):

• Se inyecta el contenido completo del skill en el contexto

• Los bloques con !`comando` se ejecutan antes de que Claude vea el contenido

• Se ejecuta en la sesión actual o en un subagente aislado, según la configuración

3. Invocación automática por Claude:

• Si la descripción del skill coincide con lo que el usuario está pidiendo, Claude lo carga solo

• Se puede desactivar con disable-model-invocation: true

4. Cambios en tiempo real:

• El sistema detecta cambios en .claude/skills/ automáticamente

• Si necesitas forzar la recarga, usa /reload-plugins

Estructura completa del frontmatter

El frontmatter YAML controla el comportamiento del skill con precisión quirúrgica:

// ~/.claude/skills/mi-skill/SKILL.md
---
name: mi-skill
description: Descripción concisa de qué hace y cuándo usarlo (máx 250 chars)
disable-model-invocation: false   # true = solo el usuario puede invocarlo
user-invocable: true              # false = solo Claude puede invocarlo (oculto del menú)
allowed-tools: Read, Grep, Bash   # herramientas sin prompt de permiso
model: claude-opus-4-6            # override del modelo para este skill
effort: high                      # low | medium | high | max
context: fork                     # fork = corre en subagente aislado
agent: Explore                    # tipo de subagente a usar
paths: "src/**/*.ts,lib/**/*.ts"  # activación automática por ruta de archivos
argument-hint: "[número de issue]" # texto de ayuda en el autocompletado
---

Tranquilo, no tienes que aprender ni usar todas las configuraciones. Como mencioné arriba, basta con name y description para que tu skill funcione. El resto de cosas las puedes usar en caso las necesites.

Inyección dinámica de contexto

Una de las funciones más útiles y menos documentadas: los bloques !`comando` ejecutan shell commands antes de que Claude procese el skill. Claude recibe el output, no el comando.

// ~/.claude/skills/resumen-pr/SKILL.md
---
name: resumen-pr
description: Resume el PR actual con los cambios y comentarios relevantes
---

Diff del PR actual:
!`gh pr diff`

Comentarios recientes:
!`gh pr view --comments`

Con base en lo anterior, genera un resumen ejecutivo del PR.

Cuando ejecutas /resumen-pr, Claude ya tiene el diff y los comentarios reales. No tienes que pegarlos manualmente.

Cómo crear tu primer Skill

Paso 1: Crea el directorio del skill

# skill-example.sh
mkdir -p ~/.claude/skills/deploy-check

Paso 2: Escribe el SKILL.md

// ~/.claude/skills/deploy-check/SKILL.md
---
name: deploy-check
description: Verifica el estado del último deploy en producción y reporta errores críticos
allowed-tools: Bash, Read
---

Estado del último deploy:
!`gh run list --limit 1 --json status,conclusion,name,createdAt`

Logs del deploy si falló:
!`gh run view --log-failed 2>/dev/null || echo "No hay deploys fallidos recientes"`

Analiza el estado del deploy y:
1. Si todo está bien, confirma con un mensaje claro
2. Si hay errores, identifica la causa raíz y propón los pasos para resolverlo
3. Si hay advertencias, menciónalas sin dramatizar

Sé directo. Sin relleno.

Paso 3: Úsalo

/deploy-check

Skills con subagente aislado

Si tu skill hace investigación profunda o tareas que no deben contaminar el contexto de la conversación actual, usa context: fork:

// ~/.claude/skills/auditoria-deps/SKILL.md
---
name: auditoria-deps
description: Audita las dependencias del proyecto en busca de vulnerabilidades y versiones desactualizadas
context: fork
agent: Explore
allowed-tools: Bash, Read, Glob
---

Realiza una auditoría completa de dependencias:

1. Ejecuta `npm audit` o `yarn audit` según el package manager detectado
2. Lista las dependencias con vulnerabilidades críticas o altas
3. Identifica dependencias desactualizadas más de 2 versiones mayores
4. Genera un reporte priorizado con las acciones recomendadas

Argumento recibido: $ARGUMENTS

El subagente corre en un contexto limpio, hace su trabajo, y te devuelve el resultado. Tu conversación principal no se llena de ruido.

Dónde se almacenan los Skills

Claude Code sigue una jerarquía de prioridad clara:

Cuando hay conflicto de nombres, la prioridad más alta gana. Los skills de proyecto son ideales para workflows específicos de un repo (review de arquitectura, generación de migraciones, etc.). Los globales son para herramientas transversales que usas en todos lados.

Los skills de proyecto también funcionan en monorepos con estructura anidada:

mi-proyecto/
├── .claude/skills/
│   └── proyecto-skill/SKILL.md       ← disponible en todo el proyecto
└── packages/
    └── frontend/
        └── .claude/skills/
            └── frontend-skill/SKILL.md ← solo se activa en packages/frontend

Skills con archivos de soporte

Para skills más complejos, puedes incluir archivos de referencia, plantillas y scripts:

~/.claude/skills/ceo-marketing/
├── SKILL.md                    ← punto de entrada requerido
├── references/
│   └── frameworks.md           ← SWOT, 4Ps, AIDA, Pirate Metrics
├── assets/
│   └── strategy-template.md    ← plantilla de plan estratégico
└── config.json                 ← configuración persistente

En el SKILL.md referencias estos archivos para que Claude sepa que existen:

// ~/.claude/skills/ceo-marketing/SKILL.md
---
name: ceo-marketing
description: Genera estrategias de marketing con frameworks probados (SWOT, 4Ps, AIDA)
---

Eres un CMO experimentado. Tienes acceso a:
- frameworks de referencia en `references/frameworks.md`
- plantillas de estrategia en `assets/strategy-template.md`

Usa $ARGUMENTS para entender el contexto del negocio y genera un plan accionable.

Comparación con otras herramientas

Cursor Rules

Cursor usa .cursorrules (o .cursor/rules/) como archivos de texto plano que se inyectan en el contexto del modelo. Son útiles para definir convenciones de código, pero no tienen slash commands, no pueden ejecutar shell commands antes de que el modelo los vea, y no hay sistema de distribución. Son instrucciones pasivas, no comandos activos.

• Source: Cursor Rules Documentation

GitHub Copilot Instructions

Copilot usa .github/copilot-instructions.md como contexto de fondo que se inyecta en todas las interacciones del repositorio. No hay slash commands, no hay subagentes, y el control es mucho más limitado. Funciona bien para convenciones de equipo, pero no puedes crear workflows específicos invocables.

• Source: GitHub Copilot Custom Instructions

Gemini CLI

Gemini CLI admite system prompts y contexto via --system flag o archivos de configuración, pero no tiene un sistema de skills o slash commands comparable. Puedes definir comportamientos globales, pero no comandos invocables con lógica propia, herramientas restringidas, o ejecución aislada.

• Source: Gemini CLI GitHub

Windsurf Rules

Windsurf (Codeium) tiene .windsurfrules similar a Cursor — texto plano inyectado como contexto. No hay slash commands, no hay sistema de distribución, y la granularidad es baja comparada con el frontmatter de Claude Code.

Casos de uso reales

1. Review diario de PRs con filtros

// ~/.claude/skills/daily-pr-review/SKILL.md
---
name: daily-pr-review
description: Filtra y revisa PRs abiertos del repositorio con clasificación por severidad
allowed-tools: Bash
argument-hint: "[--includeBackend] [--limit N] [--verbose]"
---

PRs abiertos:
!`gh pr list --json number,title,author,createdAt,additions,deletions,labels`

Clasifica cada PR con severidad:
- Crítico (cambios > 500 líneas o etiqueta breaking-change)
- Intermedio (cambios entre 100-500 líneas)
- Menor (cambios < 100 líneas)

Parámetros recibidos: $ARGUMENTS

2. Generador de migration files

// .claude/skills/gen-migration/SKILL.md
---
name: gen-migration
description: Genera archivos de migración de base de datos para el cambio descrito
allowed-tools: Read, Write, Bash
argument-hint: "<descripción del cambio de schema>"
---

Schema actual:
!`cat prisma/schema.prisma 2>/dev/null || cat db/schema.rb 2>/dev/null`

Genera una migración para: $ARGUMENTS

Sigue las convenciones del ORM detectado. Incluye rollback.

3. Auditor de seguridad

// ~/.claude/skills/sec-audit/SKILL.md
---
name: sec-audit
description: Audita el código actual en busca de vulnerabilidades OWASP Top 10
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Realiza una auditoría de seguridad del archivo o directorio: $ARGUMENTS

Busca específicamente:
- Inyección SQL / NoSQL
- XSS en templates
- Secrets hardcodeados
- Dependencias con CVEs conocidos
- Configuraciones inseguras de CORS/CSP

Reporta con severidad (Critical/High/Medium/Low) y línea exacta.

Tips y errores comunes

Tip 1: La descripción es el trigger de invocación automática

Claude decide si invocar un skill basándose en su description. Si la descripción es vaga, el skill se activará en momentos inapropiados — o nunca. Sé específico sobre cuándo debe usarse:

# Malo
description: Ayuda con marketing

# Bueno  
description: Genera planes de marketing con SWOT, 4Ps y AIDA cuando el usuario describe un negocio o producto

Tip 2: No metas todo en SKILL.md

Para skills complejos, mueve el material de referencia a archivos separados dentro del directorio del skill. El SKILL.md debería ser la lógica de orquestación, no una enciclopedia.

Tip 3: Usa context: fork para tareas de investigación

Si tu skill lee muchos archivos o genera mucho output intermedio, context: fork evita que eso contamine tu sesión principal. El resultado final sí llega a tu conversación.

Tip 4: Prueba la inyección dinámica antes de confiar en ella

Los bloques !`comando` pueden fallar silenciosamente si el comando no existe o devuelve error. Añade 2>/dev/null || echo "No disponible" como fallback en comandos que pueden no existir en todos los entornos.

Tip 5: allowed-tools reduce fricción

Si tu skill necesita ejecutar Bash o Read varias veces, declararlo en allowed-tools evita que Claude te pida permiso en cada operación. Útil para skills de automatización.

Tip 6: Usa symlinks para compartir skills entre proyectos

# symlink-skill.sh
ln -s ~/.claude/skills/deploy-check /ruta/al/proyecto/.claude/skills/deploy-check

Cuándo NO usar un Skill

Un Skill no es siempre la respuesta correcta:

• Para instrucciones permanentes del proyecto → usa CLAUDE.md

• Para automatizaciones disparadas por eventos (post-commit, post-edit) → usa Hooks en settings.json

• Para contexto de sesión simple → pásalo directamente en el chat o en el prompt del sistema

Los Skills son para workflows activos que quieres invocar explícitamente o que el modelo debe reconocer como comandos disponibles.

Conclusión

El sistema de Skills de Claude Code es, a la fecha de este artículo (abril 2026), el más completo entre las herramientas de AI coding disponibles. Slash commands invocables, inyección dinámica de contexto, ejecución aislada en subagentes, control granular de herramientas, y un sistema de distribución por plugins — ningún competidor directo tiene todo esto junto.

La curva de entrada es MUY baja, un archivo SKILL.md con diez líneas es suficiente para empezar. La profundidad es alta, ya que puedes construir workflows complejos con archivos de soporte, configuración persistente y lógica de orquestación que transforma cómo interactúas con tu codebase.