Habilidad de Claude Code: Guia completa para crear Skills (2026)

¿Estás cansado de repetir las mismas instrucciones a Claude Code en cada sesión? Pasos de code review, procedimientos de testing, reglas de commit — tu proyecto tiene flujos establecidos, pero explicarlos desde cero cada vez es ineficiente. Con Claude Code Skills puedes codificar estos flujos en /comandos que se ejecutan con una sola invocación. Personalmente he creado y uso varios Skills a diario, y han acelerado drásticamente mis tareas repetitivas. También recomiendo distribuirlos entre los miembros del equipo para estandarizar flujos de trabajo — y si te atascas escribiendo uno, simplemente pídele ayuda a la IA. En esta guía vas a aprender qué son los Skills, cómo escribir tu propio SKILL.md, la mecánica de auto-invocación, 5 ejemplos prácticos listos para copiar y pegar, y cómo desplegarlos en equipos y organizaciones.

¿Qué son los Skills? — Comandos personalizados de Claude Code

Los Skills son la forma nativa de Claude Code para encapsular instrucciones reutilizables. En lugar de escribir un prompt largo cada vez que quieres hacer un code review o generar un mensaje de commit, creas una carpeta con un archivo SKILL.md y Claude lo ejecuta con un simple /nombre-del-skill.

Piensa en los Skills como “funciones” para tu asistente de código: definen un comportamiento específico, aceptan argumentos y producen resultados consistentes. La gran ventaja es que se integran directamente en el flujo de trabajo de Claude Code sin necesidad de herramientas externas.

Conceptos básicos — Carpetas con SKILL.md

Un Skill es, en esencia, una carpeta que contiene un archivo SKILL.md. Esta carpeta se ubica dentro del directorio .claude/skills/ de tu proyecto o de tu configuración global. La estructura mínima es:

.claude/
  skills/
    review/
      SKILL.md        # Instrucciones del Skill
    tdd/
      SKILL.md
    commit/
      SKILL.md

Cuando escribes /review en Claude Code, el sistema busca la carpeta review/ dentro de .claude/skills/, lee el SKILL.md e inyecta las instrucciones en el contexto de la conversación. Esto se conoce como divulgación progresiva: las instrucciones solo se cargan cuando realmente las necesitas, ahorrando tokens valiosos del contexto.

Skills vs Custom Commands — Tabla comparativa

Antes de los Skills, la forma habitual de reutilizar instrucciones era a través de Custom Commands (archivos .claude/commands/*.md). Los Skills representan una evolución significativa:

Los Custom Commands siguen funcionando y son perfectamente válidos para tareas simples. Sin embargo, si necesitas auto-invocación, argumentos estructurados o control granular sobre cuándo se cargan las instrucciones, los Skills son la opción recomendada.

Ubicación y prioridad

Los Skills pueden existir en tres niveles, y Claude los busca en este orden de prioridad:

Si un Skill con el mismo nombre existe en varios niveles, el de proyecto tiene prioridad sobre el global, y el de Enterprise siempre se aplica (no puede ser anulado por el usuario).

Cómo escribir SKILL.md — Frontmatter e instrucciones

El archivo SKILL.md tiene dos secciones: un frontmatter en formato TOML (delimitado por +++) y las instrucciones en Markdown. El frontmatter define los metadatos del Skill, y las instrucciones son lo que Claude recibe cuando se invoca.

Estructura básica — Ejemplo de código

Veamos un ejemplo completo de un Skill para code review:

+++
description = "Realiza un code review siguiendo las convenciones del proyecto"
auto_invoke = "when the user asks to review code or a PR"

[arguments.target]
description = "Archivo o directorio a revisar"
required = true

[arguments.severity]
description = "Nivel de exigencia: strict | normal | lenient"
required = false
default = "normal"
+++

# Code Review Skill

Cuando se invoque este Skill, sigue estos pasos:

1. **Lee los archivos** indicados en `$target`
2. **Analiza** el código buscando:
   - Errores lógicos y bugs potenciales
   - Violaciones de estilo del proyecto (ver CLAUDE.md)
   - Problemas de rendimiento
   - Vulnerabilidades de seguridad
3. **Genera un informe** con el formato:
   - Resumen general (1-2 líneas)
   - Lista de hallazgos ordenada por severidad
   - Sugerencias de mejora con código corregido
4. **Ajusta la exigencia** según `$severity`:
   - `strict`: Reporta todo, incluyendo estilo y naming
   - `normal`: Solo errores, rendimiento y seguridad
   - `lenient`: Solo errores críticos y seguridad

Cuando escribes /review src/auth.ts --severity strict, Claude carga estas instrucciones, sustituye $target por src/auth.ts y $severity por strict, y ejecuta el flujo paso a paso.

Referencia completa del frontmatter

Estos son todos los campos disponibles en el frontmatter TOML:

Consejos para instrucciones efectivas

Las instrucciones dentro del SKILL.md son lo que realmente define el comportamiento del Skill. Aquí van las mejores prácticas:

• Usa listas numeradas — Los pasos secuenciales son más fáciles de seguir para Claude que los párrafos largos.
• Sé específico con los formatos de salida — Si quieres que el resultado tenga un formato determinado (tabla, lista, código), indícalo explícitamente.
• Referencia archivos del proyecto — Puedes decir “Lee las reglas de estilo en CLAUDE.md” para que Claude consulte configuraciones existentes.
• Define criterios de éxito — “El review está completo cuando has verificado los 5 puntos” es mejor que “revisa bien el código”.
• Incluye ejemplos — Si el formato de salida es complejo, incluye un ejemplo concreto en las instrucciones.

Auto-invocación — Cómo Claude carga Skills automáticamente

Una de las características más potentes de los Skills es la auto-invocación. En lugar de que tú escribas /nombre-del-skill, Claude detecta automáticamente cuándo una tarea coincide con la descripción de un Skill y lo carga sin que se lo pidas.

Divulgación progresiva

La divulgación progresiva es el mecanismo que hace posible la auto-invocación eficiente. Funciona así:

1. Inicio de sesión: Claude recibe solo la lista de Skills disponibles con sus description (pocos tokens).
2. Detección: Cuando el usuario hace una petición, Claude compara con las descripciones disponibles.
3. Carga: Si hay coincidencia, Claude carga las instrucciones completas del Skill (inyección en contexto).
4. Ejecución: Claude sigue las instrucciones del Skill para completar la tarea.

Esto significa que puedes tener 50 Skills definidos sin que consuman tokens hasta que realmente se necesiten. Solo las descripciones breves están siempre en contexto.

Control de auto-invocación

El campo auto_invoke en el frontmatter controla cuándo Claude activa el Skill automáticamente. Hay tres patrones principales:

Presupuesto de description y problemas comunes

La description es crítica para la auto-invocación: es lo que Claude lee para decidir si debe cargar el Skill. Ten en cuenta estos puntos:

• Mantenla breve pero descriptiva — Ideal: 1-2 oraciones. Las descripciones muy largas desperdician tokens que siempre están en contexto.
• Usa palabras clave claras — Si el Skill es para “code review”, incluye exactamente esas palabras en la descripción.
• Evita solapamiento — Si dos Skills tienen descripciones similares, Claude puede confundirse sobre cuál cargar. Diferencia claramente el alcance de cada uno.
• Problema común: Skill no se auto-invoca — Generalmente es porque la description no coincide con las palabras que usa el usuario. Revisa que el lenguaje sea natural y coincida con cómo la gente realmente pide esa tarea.
• Problema común: Skill se invoca cuando no debería — La description es demasiado genérica. Añade restricciones específicas en auto_invoke.

5 Skills prácticos que puedes usar hoy

A continuación te presento cinco Skills listos para copiar, adaptar y usar en tus proyectos. Cada uno resuelve un problema real de flujo de trabajo.

Veamos el código completo de cada uno:

① /review — Code Review

+++
description = "Realiza code review buscando bugs, rendimiento y seguridad"
auto_invoke = "when the user asks to review code, a PR, or a diff"

[arguments.target]
description = "Archivo, directorio o rango de diff a revisar"
required = true

[arguments.severity]
description = "strict | normal | lenient"
required = false
default = "normal"
+++

# Code Review

1. Lee los archivos o diff en `$target`
2. Revisa según nivel `$severity`:
   - **strict**: bugs, rendimiento, seguridad, estilo, naming, docs
   - **normal**: bugs, rendimiento, seguridad
   - **lenient**: solo bugs críticos y seguridad
3. Para cada hallazgo reporta:
   - Archivo y línea
   - Severidad: CRITICAL / WARNING / INFO
   - Descripción del problema
   - Código corregido (si aplica)
4. Genera un resumen final con métricas

② /tdd — Test-Driven Development

+++
description = "Implementa funcionalidad usando TDD: Red-Green-Refactor"
auto_invoke = "when the user asks to implement something with TDD or test-first"

[arguments.feature]
description = "Descripción de la funcionalidad a implementar"
required = true

[arguments.framework]
description = "jest | vitest | pytest | go"
required = false
default = "jest"
+++

# TDD Workflow

1. **RED** — Escribe tests que fallen:
   - Crea el archivo de test siguiendo convenciones del proyecto
   - Escribe tests que cubran el caso normal, edge cases y errores
   - Ejecuta los tests y verifica que FALLEN

2. **GREEN** — Implementación mínima:
   - Escribe el código mínimo para pasar los tests
   - NO añadas funcionalidad extra
   - Ejecuta los tests y verifica que PASEN

3. **REFACTOR** — Mejora el código:
   - Elimina duplicación, mejora naming, simplifica lógica
   - Ejecuta los tests después de cada cambio
   - Los tests deben seguir pasando

③ /commit — Mensajes de commit

+++
description = "Genera un mensaje de commit siguiendo Conventional Commits"
auto_invoke = "when the user asks to commit or create a commit message"
+++

# Commit Message Generator

1. Ejecuta `git diff --cached` para ver cambios en staging
2. Si no hay cambios en staging, ejecuta `git diff` y pregunta qué archivos incluir
3. Analiza los cambios y determina:
   - **Tipo**: feat / fix / refactor / docs / test / chore / perf
   - **Scope**: basado en los directorios/módulos modificados
   - **Breaking change**: si hay cambios incompatibles
4. Genera el mensaje con formato:
   ```
   tipo(scope): descripción concisa (imperativo, <72 chars)

   Cuerpo explicativo si los cambios son complejos.

   BREAKING CHANGE: si aplica
   ```
5. Muestra el mensaje al usuario para confirmación antes de ejecutar `git commit`

④ /translate — Traducción i18n

+++
description = "Extrae strings y genera archivos de traducción i18n"
auto_invoke = "when the user asks to translate, internationalize, or add i18n"

[arguments.target]
description = "Archivo o directorio con strings a extraer"
required = true

[arguments.langs]
description = "Idiomas destino separados por coma (ej: en,es,fr)"
required = true
+++

# i18n Translation

1. Lee los archivos en `$target`
2. Identifica strings visibles al usuario (UI, mensajes, errores)
3. Genera claves i18n descriptivas (ej: `auth.login.button_label`)
4. Crea/actualiza archivos de traducción para cada idioma en `$langs`:
   - Traducciones naturales, NO literales
   - Respeta pluralización del idioma destino
   - Mantiene interpolación de variables ({name}, {{count}}, etc.)
5. Reemplaza strings originales por llamadas a t() / i18n()
6. Muestra resumen de strings extraídos y archivos modificados

⑤ Convenciones de fondo — Auto-aplicado

+++
description = "Aplica las convenciones del proyecto a todo el código generado"
auto_invoke = "always"
+++

# Convenciones del Proyecto

Al generar o modificar código, aplica SIEMPRE estas reglas:

- **Naming**: camelCase para variables/funciones, PascalCase para clases/tipos
- **Errores**: Nunca silenciar errores. Usa Result/Either para errores esperados, throw para inesperados
- **Imports**: Orden: stdlib > terceros > internos. Sin imports circulares
- **Logging**: Usa el logger del proyecto (no console.log). Niveles: debug/info/warn/error
- **Archivos**: Máx 300 líneas por archivo. Si excede, proponer separación
- **Tests**: Todo código nuevo debe tener tests. Mínimo: caso feliz + caso de error

Despliegue en equipos y organizaciones

Los Skills son especialmente valiosos cuando se comparten con todo un equipo. En lugar de que cada desarrollador configure sus propias instrucciones, puedes estandarizar los flujos de trabajo de todo el equipo con Skills en el repositorio.

Skills de proyecto — Compartidos vía Git

La forma más sencilla de compartir Skills es incluir la carpeta .claude/skills/ en el repositorio del proyecto:

# Estructura recomendada para equipos
.claude/
  CLAUDE.md              # Instrucciones generales del proyecto
  skills/
    review/
      SKILL.md           # Code review con estándares del equipo
    commit/
      SKILL.md           # Formato de commits del equipo
    deploy-check/
      SKILL.md           # Checklist pre-despliegue
    onboarding/
      SKILL.md           # Guía para nuevos miembros

Ventajas de este enfoque:

• Los Skills se versionan junto con el código
• Los cambios se revisan en PR como cualquier otro código
• Nuevos miembros del equipo obtienen los Skills automáticamente al clonar
• Puedes tener Skills distintos por rama (ej: rama de release con Skills de verificación)

Provisión Enterprise

Para organizaciones grandes, la provisión Enterprise permite distribuir Skills obligatorios a todos los desarrolladores. Estos Skills se aplican automáticamente y no pueden ser desactivados por los usuarios individuales.

Casos de uso típicos de Skills Enterprise:

• Políticas de seguridad — Verificar que no se incluyan secretos en el código
• Cumplimiento regulatorio — Asegurar que el código cumple normativas (GDPR, HIPAA, etc.)
• Estándares de arquitectura — Forzar patrones aprobados por el equipo de arquitectura
• Logging y observabilidad — Asegurar que todo código incluye instrumentación adecuada

Consideraciones de seguridad

Solución de problemas — Errores comunes y soluciones

Estos son los tres problemas más frecuentes al trabajar con Skills y cómo resolverlos:

Preguntas frecuentes — Skills de Claude Code

Conclusión — Haz de Claude Code tu herramienta personalizada

Los Skills transforman a Claude Code de un asistente genérico a una herramienta adaptada a tu forma de trabajar. Cada vez que te descubras repitiendo las mismas instrucciones, es una señal de que necesitas un Skill.

Empieza con algo sencillo: un Skill de commit o de review que siga las convenciones de tu equipo. Una vez que veas el impacto en tu productividad, irás naturalmente ampliando tu colección. La divulgación progresiva garantiza que no pagarás un precio en tokens por Skills que no estés usando en ese momento.

Y recuerda: los Skills se versionan con Git. Comparte los que funcionan con tu equipo, itera sobre ellos en PR, y construye un repositorio de conocimiento operativo que mejora con cada iteración.

Artículos relacionados que te pueden interesar:

• 👉 15 técnicas de eficiencia para Claude Code
• 👉 Guía de seguridad de Claude Code
• 👉 Claude Code CLI vs Web vs Desktop

📖 Artículos Relacionados Mencionados

Eficiencia de Claude Code: 15 Tecnicas Probadas (2026)Seguridad de Claude Code CLI: 9 Pasos para Uso Empresarial [2026]Claude Code CLI vs Web vs Desktop: Comparativa 2026Comandos de Claude Code — Guía y Cheat Sheet (2026)Precios de Claude 2026: Guía completa Free vs Pro vs MaxClaude Cowork: Automatiza Tareas con 5 Casos Reales 2026

Autor

krona23

Más de 20 años en la industria IT, ocupando cargos de Director de División y CTO en múltiples empresas con servicios web a gran escala en Japón. Experiencia en desarrollo Windows, iOS, Android y web. Actualmente enfocado en la transformación AI-native. En DevGENT, comparte guías prácticas sobre editores de código con IA, herramientas de automatización y LLMs en tres idiomas.

DevGENT sobre nosotros →