Skills — Capacidades Auto-Invocadas — Dominando Claude Code

Qué Son los Skills

Los skills son archivos de instrucciones en markdown que Claude Code carga y sigue automáticamente cuando son relevantes para tu tarea actual. A diferencia de los slash commands donde escribes explícitamente un comando para activar un comportamiento, los skills se auto-invocan. Claude lee sus descripciones, las compara con lo que le estás pidiendo que haga y activa el skill apropiado sin que necesites hacer nada.

Piensa en los skills como expertos especializados que Claude consulta dependiendo de la situación. Si tienes un skill de revisión de código y le pides a Claude que revise un pull request, automáticamente toma las instrucciones del skill -- incluyendo tu checklist personalizado, estándares de calidad y formato de salida -- sin que jamás escribas un comando.

Los skills viven en el directorio .claude/skills/ de tu proyecto y siguen una estructura simple: frontmatter YAML en la parte superior para metadatos, y un cuerpo en markdown con las instrucciones reales.

Anatomía de un Skill

Cada archivo de skill tiene dos partes: frontmatter que le dice a Claude cuándo usar el skill, y un cuerpo que le dice a Claude cómo usarlo.

<!-- Archivo: .claude/skills/code-review.md -->
---
name: Code Review
description: Performs thorough code reviews checking for bugs, security issues, performance problems, and style violations. Use this when reviewing pull requests, diffs, or specific files for quality.
---

## Proceso de Revision de Codigo

Al revisar codigo, sigue estos pasos:

### 1. Verificacion de Correctitud
- Verificar que la logica maneja todos los casos limite
- Buscar errores de desplazamiento, referencias nulas y desajustes de tipos
- Asegurar que el manejo de errores cubre los modos de fallo
- Validar que las operaciones async manejan rechazos

### 2. Escaneo de Seguridad
- Buscar vulnerabilidades de inyeccion SQL, XSS y CSRF
- Verificar que la entrada del usuario esta validada y sanitizada
- Verificar que las comprobaciones de autenticacion y autorizacion estan presentes
- Asegurar que los secretos no estan hardcodeados

### 3. Revision de Rendimiento
- Identificar consultas N+1 y llamadas innecesarias a base de datos
- Buscar fugas de memoria en event listeners y suscripciones
- Buscar operaciones bloqueantes en rutas de codigo async
- Verificar que se usa paginacion para conjuntos de datos grandes

### 4. Formato de Salida
Proporcionar hallazgos en este formato:
- **Critico**: Problemas que deben corregirse antes del merge
- **Advertencia**: Problemas que deben abordarse pero no son bloqueantes
- **Sugerencia**: Mejoras que seria bueno tener

Terminar con un veredicto resumen: APROBAR, SOLICITAR CAMBIOS o NECESITA DISCUSION.

El campo description es la pieza más importante del frontmatter. Claude lo usa para decidir si activar el skill. Escribe descripciones que indiquen claramente qué hace el skill y cuándo debe usarse. Las descripciones vagas hacen que el skill se active demasiado seguido o nunca.

Cómo Funciona la Auto-Invocación

Cuando envías un prompt a Claude Code, este evalúa tu solicitud contra las descripciones de todos los skills disponibles. Si tu solicitud coincide lo suficiente con la descripción de un skill, Claude carga las instrucciones de ese skill y las incorpora en su respuesta.

Por ejemplo, si tienes el skill de code-review de arriba y escribes:

claude
> Revisa los cambios en el ultimo commit en busca de problemas

Claude reconoce esto como una tarea de revisión de código, carga el skill y sigue el checklist estructurado y formato de salida que definiste. No escribiste /code-review ni referenciaste el skill de ninguna manera -- simplemente ocurrió.

Esta coincidencia es semántica, no basada en palabras clave. Claude entiende la intención, así que "revisa este PR en busca de bugs" y "audita los últimos cambios" ambos activan el mismo skill de code-review.

Creando Tu Primer Skill

Comienza con un skill que usarías frecuentemente. Un generador de documentación es una buena opción:

<!-- Archivo: .claude/skills/generate-docs.md -->
---
name: Documentation Generator
description: Generates documentation for code including JSDoc comments, README sections, API references, and usage examples. Activate when asked to document functions, modules, or APIs.
---

## Estandares de Documentacion

Al generar documentacion:

### Para Funciones y Metodos
- Agregar JSDoc/docstring con descripcion, parametros, tipo de retorno y ejemplo
- Incluir casos limite y excepciones lanzadas en la documentacion
- Agregar etiqueta @since con la fecha actual

### Para Modulos
- Comenzar con un parrafo resumen del proposito del modulo
- Listar todas las exportaciones con descripciones de una linea
- Incluir un ejemplo de uso mostrando el patron de import mas comun

### Para Endpoints de API
- Documentar metodo HTTP, ruta, parametros de query, cuerpo de request y response
- Incluir ejemplo curl para cada endpoint
- Documentar respuestas de error con codigos de estado y mensajes
- Agregar requisitos de autenticacion

### Reglas de Estilo
- Usar tiempo presente ("Retorna el usuario" no "Retornara el usuario")
- Mantener descripciones en menos de 2 oraciones cuando sea posible
- Los ejemplos de codigo deben ser ejecutables sin modificacion

Campos del Frontmatter

Los skills soportan varios campos de frontmatter que controlan su comportamiento:

---
name: My Skill Name           # Nombre para mostrar
description: What this skill does and when to use it  # Critico para auto-invocacion
effort: medium                 # low, medium o high — indica costo computacional
shell: bash                    # Shell por defecto para ejecucion de scripts (bash o python)
---

El campo effort ayuda a Claude a decidir cómo asignar recursos. Un skill de esfuerzo low se espera que produzca resultados rápidos, mientras que un skill de esfuerzo high señala que Claude debe tomarse su tiempo y ser exhaustivo.

Usando Scripts en Skills

Los skills pueden referenciar scripts externos para tareas que van más allá de lo que las instrucciones en markdown pueden expresar. Coloca scripts en un directorio .claude/skills/scripts/ y referéncialos desde tu skill:

<!-- Archivo: .claude/skills/analyze-bundle.md -->
---
name: Bundle Analyzer
description: Analyzes JavaScript bundle size, identifies large dependencies, and suggests optimizations. Use when asked about bundle size, performance optimization, or dependency analysis.
---

## Proceso de Analisis

1. Ejecutar el script de analisis de bundle:

   node .claude/skills/scripts/analyze-bundle.js

2. Analizar la salida e identificar:
   - Tamano total del bundle y desglose por chunk
   - Dependencias mayores a 100KB
   - Paquetes duplicados incluidos en multiples chunks
   - Oportunidades de tree-shaking

3. Proporcionar recomendaciones accionables ordenadas por impacto.

El script correspondiente puede usar módulos integrados de Node.js para ejecutar tu proceso de build, leer el archivo de estadísticas resultante, analizar la información de assets y producir un análisis ordenado. El punto clave es que las instrucciones en markdown definen el marco de razonamiento mientras que los scripts manejan la recolección de datos y la computación.

Esta combinación hace que los skills sean extremadamente poderosos. Obtienes la flexibilidad de instrucciones en lenguaje natural para razonamiento de alto nivel más la precisión de código ejecutable para procesamiento de datos.

Usando Plantillas en Skills

Los skills pueden incluir plantillas de salida que Claude completa. Esto asegura formato consistente entre invocaciones:

<!-- Archivo: .claude/skills/security-audit.md -->
---
name: Security Audit
description: Performs a security audit of the project, checking dependencies, configurations, and code patterns for vulnerabilities.
---

## Procedimiento de Auditoria

Ejecutar las siguientes verificaciones y completar la plantilla de abajo.

### Verificaciones
1. Ejecutar `npm audit` y capturar la salida
2. Escanear secretos hardcodeados usando coincidencia de patrones
3. Revisar middleware de autenticacion y autorizacion
4. Verificar configuracion de headers CORS y CSP
5. Verificar manejo de variables de entorno

### Plantilla de Reporte

# Reporte de Auditoria de Seguridad — [Fecha]

## Resumen
- **Nivel de Riesgo**: [Critico / Alto / Medio / Bajo]
- **Problemas Encontrados**: [cantidad]
- **Dependencias Escaneadas**: [cantidad]

## Vulnerabilidades de Dependencias
[Lista de npm audit con severidad y remediacion]

## Hallazgos en Codigo
[Lista de problemas encontrados en el codigo fuente]

## Problemas de Configuracion
[Lista de configuraciones incorrectas]

## Recomendaciones
[Lista priorizada de acciones a tomar]

Skills vs Slash Commands

Entendiendo cuándo usar cada uno:

Slash commands se activan manualmente. Escribes /nombre-del-comando y las instrucciones se ejecutan. Son mejores para flujos de trabajo explícitos y bajo demanda como desplegar, generar notas de versión o ejecutar una secuencia específica de pasos.

Skills se activan automáticamente cuando Claude detecta relevancia. Son mejores para reglas de comportamiento continuo como cómo revisar código, cómo escribir documentación, cómo estructurar tests o cómo manejar tipos específicos de tareas.

Si te encuentras escribiendo el mismo slash command al inicio de cada sesión, probablemente debería ser un skill en su lugar. Si solo necesitas un flujo de trabajo ocasionalmente y quieres control explícito sobre cuándo se ejecuta, mantenlo como slash command.

Mejores Prácticas

Escribe descripciones como si estuvieras entrenando a un nuevo miembro del equipo para reconocer cuándo aplica este skill. Sé específico sobre las condiciones de activación. En lugar de "ayuda con testing," escribe "genera tests unitarios con cobertura completa para funciones TypeScript, incluyendo casos límite, rutas de error y configuración de mocks. Activar cuando se pida escribir tests, agregar cobertura de tests o crear archivos de test."

Mantén cada skill enfocado en una capacidad. Un skill que intenta manejar revisión de código, documentación, testing y despliegue coincidirá demasiado ampliamente y producirá resultados inconsistentes. Crea skills separados para cada responsabilidad.

Prueba tus skills iniciando una sesión fresca y dándole a Claude una tarea que debería activar el skill. Verifica que la salida siga tu formato y checklist definidos. Si el skill no se está activando, reescribe la descripción para coincidir mejor con los tipos de prompts que usas.

Prueba este ejercicio: crea tres skills para tu proyecto -- uno para revisión de código, uno para documentación y uno para generación de tests. Escribe descripciones claras para cada uno. Luego inicia una sesión fresca de Claude Code y, sin mencionar ningún skill por nombre, pide a Claude que revise un archivo, documente un módulo y escriba tests para una función. Verifica si el skill correcto se activó cada vez y refina las descripciones hasta que la activación sea confiable.

Versiona tus skills junto a tu código. Cuando todo el equipo comparte el mismo directorio .claude/skills/, todos obtienen comportamiento de IA consistente sin importar quién esté trabajando en la base de código. Esta es una de las formas más efectivas de codificar estándares de equipo en tu flujo de desarrollo asistido por IA.