Skills: usar y crear

Una Skill es un paquete de instrucciones, scripts y referencias que Claude Code carga bajo demanda. Sirven para encapsular conocimiento de dominio que reusas: cómo formatear un Excel financiero, cómo redactar un PR de tu equipo, cómo procesar un PDF de factura. Bien diseñadas, te ahorran horas a la semana.

Objetivos

• Distinguir Skills de slash commands.
• Conocer las Skills oficiales (pdf, xlsx, pptx, docx, theme-factory, skill-creator).
• Anatomía de una Skill: SKILL.md + recursos opcionales.
• Crear una Skill propia bien descrita y con triggers efectivos.
• Empaquetar y compartir Skills en tu organización.

5.1 Skill vs slash command vs sub-agente

Los tres conceptos solapan pero son distintos. Una comparativa rápida:

La diferencia clave: el slash command lo lanza el humano. La Skill la lanza el modelo cuando reconoce un patrón en lo que pides ("hazme un Excel con…" → carga xlsx).

5.2 Skills oficiales de Anthropic

Anthropic mantiene un repositorio de Skills oficiales (anthropic-skills:*) que cubren tareas habituales:

Cómo se invoca una Skill oficial

El modelo decide solo, pero tú puedes guiar:

> Genera un Excel con las ventas del Q1 desde data/ventas.csv,
  añade una pestaña con totales por región, y un gráfico de barras.

Al detectar "Excel", el modelo carga xlsx automáticamente. La Skill aporta el conocimiento concreto de cómo usar la librería openpyxl, qué patrones evitar, formatos comunes.

O puedes invocarla por nombre:

> /xlsx
> Genera un Excel con las ventas del Q1...

5.3 Anatomía de una Skill

Una Skill es una carpeta con esta estructura mínima:

my-skill/
├── SKILL.md            ← Manifest: descripción + cuándo activar + cómo usar
├── reference/          ← (opcional) Documentos de referencia que el modelo lee bajo demanda
│   ├── api-snippets.md
│   └── examples.md
└── scripts/            ← (opcional) Scripts ejecutables auxiliares
    └── validate.py

SKILL.md

Es lo único obligatorio. Frontmatter YAML + cuerpo Markdown:

---
name: invoice-qa
description: Validación y resumen de facturas en PDF. Trigger cuando el usuario menciona "factura", "invoice", "albarán" o sube un PDF de factura.
allowed-tools: Read, Bash(pdftotext:*), Bash(jq:*)
version: 1.0.0
---

# Invoice QA

Esta skill se activa cuando el usuario quiere extraer datos estructurados
o validar una factura PDF.

## Cuándo activar

- Frases que mencionen "factura", "invoice", "albarán", "factura recibida".
- Cuando el usuario sube un fichero .pdf con nombre que contenga
  "invoice", "factura", "fra", "fact".

## Pasos

1. Convertir el PDF a texto con pdftotext -layout.
2. Extraer: NIF emisor, NIF receptor, fecha, número, base, IVA, total.
3. Validar:
   - NIF español con dígito de control correcto.
   - base + IVA = total (margen 0,01€).
   - fecha en formato dd/mm/yyyy o yyyy-mm-dd.
4. Devolver un JSON estructurado con los campos extraídos.

## Cuándo NO activar

- Si el PDF tiene una pinta de albarán sin datos fiscales.
- Si el usuario pide "resumir el contenido" — es lectura, no validación.

## Recursos

- reference/nif-validation.md → algoritmo de validación de NIF
- reference/iva-tipos.md → tipos de IVA vigentes en España

Frontmatter de SKILL.md

5.4 Escribir una buena description

El description es la decisión binaria de "¿esta skill aplica al prompt actual?". Una description vaga = skill que nunca se activa. Una description que abarca demasiado = skill que se activa cuando no debería.

Estructura recomendada de la description

1. Qué hace en 1 frase.
2. Triggers (palabras o patrones que la activan).
3. Anti-triggers si compite con otras skills.

Ejemplo bien estructurado (de la skill xlsx oficial):

description: Use this skill any time a spreadsheet file is the primary
input or output. This means any task where the user wants to: open, read,
edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding
columns, computing formulas, formatting, charting, cleaning messy data);
create a new spreadsheet from scratch or from other data sources; or
convert between tabular file formats. Trigger especially when the user
references a spreadsheet file by name. Do NOT trigger when the primary
deliverable is a Word document, HTML report, standalone Python script, or
database pipeline.

5.5 Tu primera Skill propia

Vamos a crear una Skill llamada pr-summary que resume un pull request al estilo de tu equipo.

Estructura

.claude/skills/pr-summary/
├── SKILL.md
└── reference/
    └── plantilla-pr.md

SKILL.md

---
name: pr-summary
description: Genera el resumen de un Pull Request siguiendo el formato del
  equipo. Trigger cuando el usuario pida "resumen del PR", "PR description",
  "summary del pull request", o cuando esté preparando una descripción de
  PR a partir de un branch con commits.
allowed-tools: Bash(git diff:*), Bash(git log:*), Read
version: 1.0.0
---

# PR Summary

Esta skill se activa al preparar la descripción de un Pull Request.
Sigue la plantilla del equipo (ver reference/plantilla-pr.md).

## Pasos

1. Ejecutar git log origin/main..HEAD --oneline para listar commits del branch.
2. Ejecutar git diff --stat origin/main..HEAD para resumir cambios.
3. Leer reference/plantilla-pr.md para conocer la estructura.
4. Generar la descripción rellenando:
   - Resumen ejecutivo (1-2 frases, qué problema resuelve)
   - Cambios clave (3-5 bullets)
   - Test plan (qué se ha verificado)
   - Riesgos (qué podría romperse)
   - Issue/Ticket vinculado (si lo hay en commits)

## Cuándo NO activar

- Para code review (usar /review).
- Para análisis de seguridad (usar /security-review).

## Output

Devuelve la descripción lista para copiar y pegar en GitHub/GitLab.
NO abre el PR. NO hace push. Solo genera el texto.

reference/plantilla-pr.md

# Plantilla de PR del equipo

## Resumen
<1-2 frases. Qué problema resuelve este PR. Lenguaje no técnico.>

## Cambios clave
- ...
- ...

## Test plan
- [ ] Tests unitarios pasan (npm test)
- [ ] Verificación manual: ...
- [ ] No se ha tocado: ...

## Riesgos
<Qué podría romperse, qué requiere atención del reviewer.>

## Ticket
Closes #123 (si aplica)

Una vez creada, prueba:

> Prepárame un resumen de mi PR actual

Verás cómo el agente reconoce el trigger y carga la skill. Si por algún motivo no la carga, puedes invocarla:

> /pr-summary

5.6 Skill con scripts auxiliares

Para tareas con lógica determinista (validar un NIF, parsear un formato muy concreto), es buena idea poner un script en scripts/ y referenciarlo en SKILL.md:

my-skill/
├── SKILL.md
└── scripts/
    └── validate-nif.py

En el SKILL.md:

## Validación

Para validar el dígito de control del NIF, usa el script auxiliar:

  python scripts/validate-nif.py <NIF>

Devuelve "OK" o "INVALID". El algoritmo está implementado correctamente
y testado — no reimplementes la validación a mano.

Esto evita que el modelo invente la lógica de validación cada vez (con riesgo de equivocarse). Le das una herramienta determinista y le pides que la use.

5.7 Empaquetar y distribuir Skills

Tres niveles de instalación:

Nivel 1 · Repo (versionada)

Carpeta .claude/skills/ dentro del repositorio. Pertenece al equipo, viaja con el código. Solo está disponible cuando trabajas en ese repo.

Nivel 2 · Usuario (global personal)

Carpeta ~/.claude/skills/. Disponible en todas tus sesiones, en cualquier repo. Útil para tus skills personales.

Nivel 3 · Plugin

Empaquetadas en un plugin, instalables a nivel organización. Requiere un fichero plugin.json en la raíz:

{
  "name": "qlcube-skills",
  "version": "1.0.0",
  "description": "Skills internas de Qlcube para flujo de trabajo de ingeniería",
  "skills": ["pr-summary", "release-notes", "fundae-validation"]
}

Se distribuye como fichero .plugin que cada miembro del equipo instala con /install-plugin.

5.8 Anti-patrones de Skills

• Skills demasiado generales. "Helper general" no es una skill, es ruido. Las skills resuelven UN problema concreto.
• Description redactada para el humano, no para el modelo. El modelo lee la description para decidir si cargar. Escríbela orientada a triggers, no a marketing.
• Skill que sustituye al razonamiento. Si tu skill dice "haz X y Y", el modelo lo hace, pero no aprende a generalizar. Mejor una skill que ofrezca plantillas y herramientas y deje al modelo decidir.
• No actualizar el version. Si cambias una skill significativamente, sube version. Te ayuda a depurar bugs en el equipo.
• Hacer que la skill commitee o pushee. Las skills generan, no publican. Mantén la separación.

Práctica

Test de comprensión

Resumen

• Skill = paquete de instrucciones + recursos que el modelo carga bajo demanda.
• Skills oficiales: pdf, xlsx, pptx, docx, theme-factory, web-artifacts-builder, skill-creator.
• Anatomía: SKILL.md + opcional reference/ + scripts/.
• El campo description manda. Estructúralo: qué hace + triggers + anti-triggers.
• Distribución: .claude/skills/ en repo, ~/.claude/skills/ personal, plugins para org.

Siguiente módulo: subagentes. Cómo Claude Code delega tareas a versiones especializadas de sí mismo y aprovechar el paralelismo.