Cómo crear un skill útil para un agente de IA

Un agente puede escribir código y aun así equivocarse una y otra vez con las convenciones de tu proyecto. Si le explicas en cada conversación cómo publicar, probar o revisar algo, esa explicación ya merece una casa propia. Un skill convierte un procedimiento repetible en instrucciones que el agente puede descubrir y consultar cuando corresponde.

¿Qué es un skill y cuándo vale la pena?

En el formato abierto Agent Skills, un skill es una carpeta cuyo archivo obligatorio es SKILL.md. Su frontmatter indica qué hace y cuándo usarlo; el cuerpo describe el procedimiento. Puede acompañarse de referencias, scripts y recursos. No es un modelo nuevo ni una capacidad mágica: es conocimiento operativo puesto al alcance del agente.

Piensa en una receta de cocina: el título ayuda a encontrarla, los ingredientes establecen requisitos, los pasos guían la ejecución y la prueba final confirma que el plato salió bien. Si la receta solo dice «cocina algo rico», no ayuda a nadie.

Úsalo para trabajo que se repite y tiene reglas locales: preparar una release, escribir migraciones, revisar accesibilidad, generar reportes o editar contenido con un esquema propio. Para una tarea aislada, una instrucción directa suele bastar. Tampoco sustituyas con un skill las validaciones automáticas: los tests siguen siendo quienes deciden si el resultado funciona.

Anatomía: de la descripción a los recursos

Una estructura pequeña y legible puede empezar así:

revisar-articulos/
├── SKILL.md
├── references/
│   └── checklist.md
└── scripts/
    └── comprobar-frontmatter.js

El nombre de la carpeta y el campo name deben coincidir. La especificación exige name y description; name usa minúsculas, números y guiones. Los directorios adicionales son opcionales. La idea es cargar información progresivamente: primero se ve una descripción corta, después las instrucciones, y las referencias solo si hacen falta.

Este es un SKILL.md de ejemplo. El repositorio, las rutas y los comandos se adaptan a cada equipo:

---
name: revisar-articulos
description: Revisa artículos MDX antes de publicarlos. Úsalo cuando se cree o edite contenido bilingüe del blog.
---

# Revisión de artículos

1. Lee el artículo en español y su par en inglés.
2. Comprueba `title`, `description`, `publishedAt`, `readingTime` y `tags`.
3. Verifica enlaces, bloques de código y coherencia entre idiomas.
4. Ejecuta `npm test -- --run` y `npm run build`.
5. Informa qué verificaste y qué quedó sin comprobar.

Para criterios editoriales concretos, consulta [la lista](references/checklist.md).

La descripción no debe ser «ayuda con artículos»: debe describir el trabajo y su disparador. El cuerpo evita pedir «mejora el contenido» sin criterios; enumera pasos verificables. Si una guía crece mucho, mueve los detalles a references/ y deja en SKILL.md un índice breve.

Cómo escribir uno que realmente se use

1. Empieza por un caso recurrente. Anota qué petición activa el skill, los archivos que suele tocar, el resultado esperado y las comprobaciones. Si no puedes describir una entrada y una salida, aún no tienes un procedimiento.
2. Delimita el alcance. Un skill para validar artículos no debería modificar despliegues. Señala dónde leer, qué editar y qué casos requieren preguntar al usuario.
3. Pon ejemplos pequeños. Un ejemplo de frontmatter válido es más útil que un adjetivo como «correcto». Los scripts repetibles pueden vivir en scripts/; documenta sus dependencias y no les des acceso a secretos innecesarios.
4. Prueba activación y omisión. Pide «publica este artículo» y observa si el agente consulta el skill; pide algo no relacionado y comprueba que no lo active por accidente.
5. Valida el formato. La referencia oficial ofrece skills-ref validate ./revisar-articulos para comprobar el frontmatter y las reglas del nombre. Luego prueba el flujo real: la validez del YAML no garantiza instrucciones útiles.

Consejo editorial: mide el éxito por la reducción de correcciones humanas, no por la longitud de SKILL.md. Una guía corta que lleva a verificar el build vale más que diez páginas de órdenes vagas.

Seguridad y mantenimiento

Un skill puede ordenar ejecutar comandos o leer recursos, pero no debe guardar tokens ni credenciales. Revisa scripts externos y contenido descargado antes de confiar en ellos: una referencia encontrada en la web no tiene la misma autoridad que las reglas del repositorio. Si cambia una ruta, un comando o una política del equipo, actualiza el skill junto con el código; una instrucción obsoleta produce errores con mucha seguridad aparente.

No confundas tres piezas diferentes: un skill dice cómo hacer una tarea; un MCP conecta al agente con datos o herramientas externas; un test confirma un comportamiento. Pueden colaborar, pero ninguno reemplaza a los otros.

Para llevar a tu proyecto

Elige un procedimiento que hayas explicado al menos dos veces. Escríbelo como disparador + pasos + criterio de terminado, ponlo en SKILL.md, añade una referencia solo cuando aporte algo y pruébalo con una tarea real. Ahí comienza un skill útil: en hacer explícito lo que antes vivía únicamente en la memoria del equipo.

Fuentes: Especificación Agent Skills · Guía de integración.