Dominar Claude Code Parte 5: Skills

Ya construiste comandos personalizados. Son geniales para flujos de trabajo que activas explícitamente—/review, /commit, /deploy. Pero ¿qué pasa con el conocimiento que Claude debería aplicar automáticamente sin que tú tengas que recordar invocarlo?

Para eso sirven los Skills. Son módulos de conocimiento especializado que Claude descubre y carga cuando son relevantes, no cuando los llamas explícitamente. Piensa en los Comandos como herramientas que tú agarras; los Skills son experiencia que Claude desarrolla.

Comandos vs Skills: ¿Cuál es la Diferencia?

La distinción importa porque cambia cómo estructuras tu automatización.

Comandos Slash (de la Parte 4):

• Los invocas explícitamente: /review, /commit
• Se cargan inmediatamente cuando los llamas
• Ideales para flujos de trabajo que quieres activar intencionalmente
• Archivos markdown simples con frontmatter opcional

Skills:

• Claude los invoca automáticamente cuando tu solicitud coincide
• Carga diferida—solo la descripción se lee al inicio, el contenido completo se carga al usar
• Ideales para estándares, patrones y conocimiento especializado que Claude siempre debería aplicar
• Pueden incluir archivos de soporte, ejemplos y scripts ejecutables

Aquí está el modelo mental: los Comandos son verbos (cosas que haces), los Skills son experiencia (cosas que Claude sabe).

Cuando dices "revisa este PR", podrías querer que Claude:

1. Ejecute tu comando /review (acción explícita)
2. Aplique los estándares de code review de tu equipo desde un Skill (conocimiento automático)

Ambos tienen su lugar.

Cómo Funcionan los Skills Realmente

La magia de los Skills es la revelación progresiva. Este es el flujo:

Al inicio: Claude lee solo el name y la description del archivo SKILL.md de cada Skill. Overhead mínimo.

Cuando haces una solicitud: Claude compara tu solicitud con las descripciones de los Skills. Si hay coincidencia, pregunta: "Encontré un Skill que podría ayudar. ¿Quieres que lo use?"

Al confirmar: El contenido completo de SKILL.md se carga en contexto. Los archivos de soporte se cargan solo si Claude los necesita durante la ejecución.

Esto significa que puedes tener docenas de Skills sin penalización de rendimiento. Se cargan bajo demanda, no de antemano.

Tip: Escribe las descripciones de los Skills con palabras clave que los usuarios dirían naturalmente. "Ayuda con documentos" no se activará. "Revisar pull requests usando guías de seguridad OWASP y estándares de formato del equipo" sí lo hará.

Estructura de Archivos de un Skill

Los Skills viven en directorios con un archivo SKILL.md obligatorio:

.claude/skills/
└── code-review/
    ├── SKILL.md           # Obligatorio - instrucciones y frontmatter
    ├── examples/          # Opcional - ejemplos de salida
    │   ├── good-review.md
    │   └── bad-review.md
    ├── templates/         # Opcional - plantillas de salida
    │   └── review-template.md
    └── scripts/           # Opcional - helpers ejecutables
        └── lint-check.sh

Restricciones clave:

• SKILL.md es obligatorio (nombre de archivo sensible a mayúsculas)
• Mantén SKILL.md por debajo de 500 líneas para rendimiento óptimo
• Los archivos de soporte se descubren vía enlaces en SKILL.md
• Los scripts se ejecutan sin cargar su código fuente en contexto—solo la salida consume tokens

Dónde Viven los Skills

Los Skills siguen una jerarquía—los niveles superiores sobreescriben a los inferiores:

Enterprise — Configuraciones gestionadas para todos los usuarios de la organización (máxima prioridad)

Personal — ~/.claude/skills/ — Tus Skills, disponibles en todos los proyectos

Proyecto — .claude/skills/ — Skills del equipo, commiteados a git

Plugin — skills/ dentro del directorio del plugin — Disponibles para cualquiera con el plugin instalado

La división es similar a los Comandos: los Skills personales te acompañan a todas partes, los Skills del proyecto se comparten con tu equipo.

La Plantilla de SKILL.md

Aquí está la anatomía de un Skill bien estructurado:

---
Name: code-review
Description: "Review pull requests using OWASP security guidelines, performance best practices, and team formatting standards"
Allowed-tools: Read, Grep, Glob
Model: claude-sonnet-4-5-20250929
---
# Code Review Standards

## Purpose
Apply consistent code review standards across all PRs.

## When to Use
- Reviewing pull requests
- Checking code for security issues
- Validating against team conventions

## Instructions

### Security Checks
1. SQL injection vulnerabilities
2. XSS attack vectors
3. Authentication bypasses
4. Sensitive data exposure

### Performance Checks
1. N+1 query patterns
2. Unnecessary re-renders
3. Memory leaks
4. Blocking operations

### Style Checks
1. Naming conventions per team standards
2. Function length (max 50 lines)
3. Cyclomatic complexity

## Output Format
Organize findings by severity:
- 🚨 Critical (blocks merge)
- ⚠️ Warnings (should fix)
- 💡 Suggestions (nice to have)

## Examples
See ./examples/good-review.md for proper format.

Opciones de Frontmatter

Los Skills soportan configuración poderosa a través del frontmatter YAML:

name (obligatorio) — Identificador del Skill. Solo minúsculas, números, guiones. Máximo 64 caracteres.

description (obligatorio) — Qué hace y cuándo usarlo. Máximo 1024 caracteres. Así es como Claude compara las solicitudes con los Skills—hazlo descriptivo.

allowed-tools — Herramientas que Claude puede usar sin prompts de permisos cuando este Skill está activo. Separadas por comas o lista YAML.

model — Sobreescribir el modelo cuando este Skill se ejecuta. Útil para tareas de razonamiento complejo.

context — Establece fork para ejecutar en un contexto de sub-agente aislado con historial de conversación separado.

agent — Tipo de agente cuando context: fork está configurado. Opciones: Explore, Plan, general-purpose, o personalizado.

hooks — Define hooks con alcance al Skill: PreToolUse, PostToolUse, Stop.

user-invocable — Establece false para ocultar del menú / mientras permite auto-descubrimiento.

disable-model-invocation — Establece true para prevenir que Claude lo invoque programáticamente (pero sigue visible en el menú).

Creando tu Primer Skill

Vamos a construir un Skill práctico: una guía de TDD (Desarrollo Guiado por Tests) que Claude aplica automáticamente cuando estás escribiendo tests.

Paso 1: Crea el Directorio

Mkdir -p .claude/skills/tdd

Paso 2: Crea SKILL.md

Cat > .claude/skills/tdd/SKILL.md << 'EOF'
---
Name: tdd
Description: "Apply test-driven development workflow when writing tests, implementing features with tests, or following red-green-refactor cycle"
Allowed-tools: Read, Write, Edit, Bash(npm test:*), Bash(bun test:*)
---
# Test-Driven Development

## Purpose
Guide development through proper TDD: Red → Green → Refactor.

## When to Use
- When user asks to "add a feature with tests"
- When user mentions "TDD" or "test-driven"
- When creating new functionality that requires tests
- When user asks to implement something "the right way"

## The TDD Cycle

### Phase 1: Red (Write Failing Test)
1. Understand the requirement fully
2. Write the simplest test that fails
3. Verify the test fails for the RIGHT reason
4. DO NOT write implementation yet

### Phase 2: Green (Make It Pass)
1. Write minimal code to pass the test
2. No extra features, no edge cases yet
3. Ugly code is acceptable—just make it green

### Phase 3: Refactor (Clean Up)
1. Improve code quality
2. Remove duplication
3. Better naming
4. Tests MUST stay green

### Repeat
For each new behavior, start the cycle again.

## Anti-Patterns to Avoid
- Writing implementation before tests
- Writing multiple tests at once
- Refactoring while tests are red
- Skipping the refactor phase

## Example Session
See ./examples/tdd-session.md for a complete walkthrough.
EOF

Paso 3: Añade un Ejemplo

Mkdir -p .claude/skills/tdd/examples
Cat > .claude/skills/tdd/examples/tdd-session.md << 'EOF'
# TDD Session: Adding Email Validation

## Requirement
Validate email format in user registration.

## Cycle 1: Basic Validation

### Red
```typescript
// user.test.ts
It('should reject invalid email format', () => {
  expect(() => new User('notanemail')).toThrow('Invalid email');
});
```
Run: `npm test` → FAILS (User doesn't validate emails yet)

### Green
```typescript
// user.ts
Constructor(email: string) {
  if (!email.includes('@')) {
    throw new Error('Invalid email');
  }
  this.email = email;
}
```
Run: `npm test` → PASSES

### Refactor
Extract validation:
```typescript
Private validateEmail(email: string): void {
  if (!email.includes('@')) {
    throw new Error('Invalid email');
  }
}
```

## Cycle 2: Domain Validation

### Red
```typescript
It('should reject email without domain', () => {
  expect(() => new User('test@')).toThrow('Invalid email');
});
```
...continue cycle...
EOF

Paso 4: Úsalo

Ahora cuando digas "vamos a añadir validación de email con testing apropiado", Claude:

1. Reconocerá que esto coincide con la descripción del Skill TDD
2. Preguntará si quieres usar el Skill TDD
3. Seguirá el ciclo Red → Green → Refactor automáticamente

La Colección Superpowers

La biblioteca de Skills más popular es obra/superpowers con más de 16.5k estrellas. Está probada en batalla y cubre flujos de trabajo de desarrollo comunes.

Instalación

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

O clona directamente:

Git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers

Nota: Los Skills usan espacios de nombres por directorio de forma similar a cómo se organizan los comandos en la Parte 4. Los mismos patrones organizativos aplican—los subdirectorios crean espacios de nombres para mejor organización.

Skills Clave Incluidos

/superpowers:brainstorm — Ideación estructurada antes de comenzar features complejas. Úsalo antes de lanzarte al código.

/superpowers:write-plan — Crea planes de implementación para migraciones o refactorizaciones multi-archivo.

/superpowers:execute-plan — Ejecuta planes en lotes controlados con puntos de control.

/superpowers:tdd — Desarrollo guiado por tests con el ciclo completo Red/Green/Refactor.

/superpowers:debug — Depuración sistemática con rastreo de causa raíz.

Por Qué Funciona

Superpowers no son solo prompts—son patrones probados en producción. El Skill de TDD, por ejemplo, incluye:

• Detección de anti-patrones (escribir tests después del código)
• Patrones de testing asíncrono
• Estructura adecuada de assertions
• Disparadores de refactorización

Estos patrones provienen del uso real a través de miles de desarrolladores.

Ideas Prácticas de Skills

Aquí hay Skills que vale la pena construir para tu equipo:

Documentación de API — Aplicar automáticamente tus estándares de documentación de API cuando Claude escribe o actualiza endpoints.

Manejo de Errores — Enforcar patrones consistentes de manejo de errores (tu clase ApiError, formato de logging, mensajes para el usuario).

Patrones de Base de Datos — Aplicar las convenciones de tu equipo para queries, transacciones, migraciones.

Revisión de Seguridad — Verificar automáticamente los problemas OWASP Top 10 al revisar código.

Patrones de Componentes — Enforcar la estructura y nomenclatura de componentes React/Vue/Svelte.

Mensajes de Commit — Aplicar el formato de conventional commits automáticamente.

Skills + Scripts: La Combinación Poderosa

Algo infrautilizado: los Skills pueden incluir scripts ejecutables que se ejecutan sin cargar su código fuente en contexto.

.claude/skills/security-audit/
├── SKILL.md
└── scripts/
    ├── check-dependencies.sh
    ├── scan-secrets.py
    └── validate-permissions.js

En tu SKILL.md:

## Available Scripts

Run these for automated checks:
- `./scripts/check-dependencies.sh` - Scan for vulnerable packages
- `./scripts/scan-secrets.py` - Find hardcoded secrets
- `./scripts/validate-permissions.js` - Check file permissions

Claude puede ejecutar estos scripts, pero solo la salida consume contexto—no el código fuente del script. Esto es perfecto para lógica de validación compleja que es más confiable como código testeado que como comandos generados por LLM.

Skills vs Comandos: Cuándo Usar Cada Uno

Usa Comandos cuando:

• Quieres control explícito sobre cuándo algo se ejecuta
• El flujo de trabajo es iniciado por el usuario (deploy, commit, generar)
• Necesitas pasar argumentos ($ARGUMENTS, $1, $2)
• La acción es discreta y autónoma

Usa Skills cuando:

• El conocimiento debería aplicarse automáticamente según el contexto
• Quieres estándares consistentes sin tener que recordar invocarlos
• La experiencia abarca múltiples tipos de solicitudes
• Estás codificando conocimiento del equipo que Claude siempre debería tener

Usa ambos juntos:

• El comando /review activa la revisión
• El Skill code-review proporciona los estándares a aplicar

Disponibilidad de Skills

Los Skills requieren un plan de pago:

• Pro, Max, Team, Enterprise — Soporte completo de Skills
• Tier gratuito — Sin Skills

Si estás en un plan gratuito y quieres codificar conocimiento del equipo, usa el directorio .claude/rules/ de la Parte 3 en su lugar. Las reglas siempre se cargan; los Skills tienen carga diferida.

Descubriendo Skills

Temas de GitHub:

Https://github.com/topics/claude-skills

Colecciones de la Comunidad:

• obra/superpowers — Patrones de desarrollo fundamentales
• obra/superpowers-skills — Skills contribuidos por la comunidad
• SkillsMP — Marketplace de Skills para Claude/ChatGPT

La Especificación de Agent Skills — Publicada en diciembre de 2025 como un estándar abierto. OpenAI adoptó el mismo formato para Codex CLI y ChatGPT, así que los Skills que construyes para Claude funcionan en diferentes herramientas.

Qué Sigue

Los Skills le dan a Claude conocimiento especializado que se activa automáticamente. Pero ¿qué pasa si necesitas que Claude haga múltiples cosas simultáneamente? ¿Y si una tarea pudiera beneficiarse de la ejecución paralela?

Ahí es donde entran los Subagentes. En la Parte 6: Subagentes, exploraremos cómo crear agentes especializados que trabajan en paralelo—ejecutando tests mientras generan documentación mientras verifican problemas de seguridad, todo a la vez.