Agent Skills

En el Radar compartido: Trial (valoración de la edición aportada).

Cómo funciona

Cada directorio contiene SKILL.md con nombre, descripción e instrucciones; puede incluir scripts, referencias y plantillas. El agente descubre metadatos y carga el detalle bajo demanda.

Ejemplo de uso

Una skill de migraciones explica cuándo aplicarse, enlaza recetas aprobadas y ofrece un script de verificación. El agente consulta esos recursos al recibir una actualización de framework.

Anatomía de una skill

.claude/skills/migrar-spring-boot/
├── SKILL.md              # obligatorio: metadatos + instrucciones
├── referencias/
│   └── cambios-3x.md     # se lee solo si hace falta
├── scripts/
│   └── verificar.sh      # se ejecuta, no se carga en el contexto
└── plantillas/
    └── application.yml

---
name: migrar-spring-boot
description: Migra servicios de Spring Boot 2.x a 3.x. Úsala cuando el usuario pida actualizar Spring Boot, pasar de javax a jakarta o cuando falle el build tras subir la versión del parent.
---

# Migración a Spring Boot 3

1. Comprueba la versión actual en `pom.xml` y que el proyecto compila.
2. Ejecuta la receta de OpenRewrite `UpgradeSpringBoot_3_5` (ver `referencias/cambios-3x.md`).
3. Resuelve manualmente lo que la receta no cubra: seguridad, propiedades renombradas.
4. Ejecuta `scripts/verificar.sh`; no des la tarea por terminada si falla.

Carga progresiva

Nivel	Qué se carga	Cuándo
1. Metadatos	name y description	Siempre, de todas las skills (pocas decenas de tokens cada una)
2. Instrucciones	Cuerpo de SKILL.md	Cuando la tarea coincide con la descripción
3. Recursos	Referencias, scripts, plantillas	Solo si las instrucciones los necesitan

Así se pueden tener decenas de skills instaladas sin llenar el contexto: es la aplicación directa de progressive context disclosure.

Escribir una buena descripción

La descripción decide si la skill se activa. Debe decir qué hace y cuándo usarla, con las palabras que el usuario usaría:

Débil	Mejor
«Ayuda con PDFs»	«Extrae texto y tablas de PDF, rellena formularios y une archivos. Úsala cuando se mencione un .pdf»
«Skill de despliegue»	«Despliega servicios en Cloud Run con canary. Úsala al pedir desplegar, promover o hacer rollback»

Skills frente a otras piezas

Pieza	Cuándo usarla
AGENTS.md / CLAUDE.md	Convenciones que aplican a casi todas las tareas
Skill	Procedimiento especializado que solo se necesita a veces
Servidor MCP	Acceso a un sistema externo (datos, APIs)
Subagente	Tarea delegada con su propio contexto

Distribución y gobierno

El formato es abierto y lo leen varios agentes (Claude Code, Codex, Cursor, GitHub Copilot y otros). Se distribuyen en el repositorio, en la carpeta personal o en paquetes (plugin marketplace). Un archivo de bloqueo con versiones y hashes permite saber exactamente qué skills usa un proyecto. Revisa los scripts incluidos como cualquier dependencia: se ejecutan con los permisos del agente.

Criterios de implementación

Versionar el paquete y evaluar tareas representativas antes de distribuirlo. La carga selectiva reduce contexto, pero ejecutar recursos exige permisos y controles independientes.