Skills — Capacidades Auto-Invocadas — Dominando Claude Code

Que Son los Skills

Los skills son archivos de instrucciones en markdown que Claude Code carga y sigue automaticamente cuando son relevantes para tu tarea actual. A diferencia de los slash commands donde escribes explicitamente un comando para activar un comportamiento, los skills se auto-invocan. Claude lee sus descripciones, las compara con lo que le estas 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 situacion. Si tienes un skill de revision de codigo y le pides a Claude que revise un pull request, automaticamente toma las instrucciones del skill -- incluyendo tu checklist personalizado, estandares de calidad y formato de salida -- sin que jamas 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.

Anatomia de un Skill

Cada archivo de skill tiene dos partes: frontmatter que le dice a Claude cuando usar el skill, y un cuerpo que le dice a Claude como 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 mas importante del frontmatter. Claude lo usa para decidir si activar el skill. Escribe descripciones que indiquen claramente que hace el skill y cuando debe usarse. Las descripciones vagas hacen que el skill se active demasiado seguido o nunca.

Como Funciona la Auto-Invocacion

Cuando envias un prompt a Claude Code, este evalua tu solicitud contra las descripciones de todos los skills disponibles. Si tu solicitud coincide lo suficiente con la descripcion 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 revision de codigo, 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 ocurrio.

Esta coincidencia es semantica, no basada en palabras clave. Claude entiende la intencion, asi que "revisa este PR en busca de bugs" y "audita los ultimos cambios" ambos activan el mismo skill de code-review.

Creando Tu Primer Skill

Comienza con un skill que usarias frecuentemente. Un generador de documentacion es una buena opcion:

<!-- 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 como asignar recursos. Un skill de esfuerzo low se espera que produzca resultados rapidos, mientras que un skill de esfuerzo high senala que Claude debe tomarse su tiempo y ser exhaustivo.

Usando Scripts en Skills

Los skills pueden referenciar scripts externos para tareas que van mas alla de lo que las instrucciones en markdown pueden expresar. Coloca scripts en un directorio .claude/skills/scripts/ y referencialos 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 modulos integrados de Node.js para ejecutar tu proceso de build, leer el archivo de estadisticas resultante, analizar la informacion de assets y producir un analisis ordenado. El punto clave es que las instrucciones en markdown definen el marco de razonamiento mientras que los scripts manejan la recoleccion de datos y la computacion.

Esta combinacion hace que los skills sean extremadamente poderosos. Obtienes la flexibilidad de instrucciones en lenguaje natural para razonamiento de alto nivel mas la precision de codigo 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 cuando usar cada uno:

Slash commands se activan manualmente. Escribes /nombre-del-comando y las instrucciones se ejecutan. Son mejores para flujos de trabajo explicitos y bajo demanda como desplegar, generar notas de version o ejecutar una secuencia especifica de pasos.

Skills se activan automaticamente cuando Claude detecta relevancia. Son mejores para reglas de comportamiento continuo como como revisar codigo, como escribir documentacion, como estructurar tests o como manejar tipos especificos de tareas.

Si te encuentras escribiendo el mismo slash command al inicio de cada sesion, probablemente deberia ser un skill en su lugar. Si solo necesitas un flujo de trabajo ocasionalmente y quieres control explicito sobre cuando se ejecuta, mantenlo como slash command.

Mejores Practicas

Escribe descripciones como si estuvieras entrenando a un nuevo miembro del equipo para reconocer cuando aplica este skill. Se especifico sobre las condiciones de activacion. En lugar de "ayuda con testing," escribe "genera tests unitarios con cobertura completa para funciones TypeScript, incluyendo casos limite, rutas de error y configuracion de mocks. Activar cuando se pida escribir tests, agregar cobertura de tests o crear archivos de test."

Manten cada skill enfocado en una capacidad. Un skill que intenta manejar revision de codigo, documentacion, testing y despliegue coincidira demasiado ampliamente y producira resultados inconsistentes. Crea skills separados para cada responsabilidad.

Prueba tus skills iniciando una sesion fresca y dandole a Claude una tarea que deberia activar el skill. Verifica que la salida siga tu formato y checklist definidos. Si el skill no se esta activando, reescribe la descripcion para coincidir mejor con los tipos de prompts que usas.

Prueba este ejercicio: crea tres skills para tu proyecto -- uno para revision de codigo, uno para documentacion y uno para generacion de tests. Escribe descripciones claras para cada uno. Luego inicia una sesion fresca de Claude Code y, sin mencionar ningun skill por nombre, pide a Claude que revise un archivo, documente un modulo y escriba tests para una funcion. Verifica si el skill correcto se activo cada vez y refina las descripciones hasta que la activacion sea confiable.

Versiona tus skills junto a tu codigo. Cuando todo el equipo comparte el mismo directorio .claude/skills/, todos obtienen comportamiento de IA consistente sin importar quien este trabajando en la base de codigo. Esta es una de las formas mas efectivas de codificar estandares de equipo en tu flujo de desarrollo asistido por IA.