Crear skills para tu agente

Una skill es un manual que le das a tu agente de IA para que deje de improvisar y haga una tarea como lo haría alguien que ya la hizo cien veces. En vez de re-explicar el mismo procedimiento en cada chat, lo escribís una sola vez, el agente lo encuentra solo cuando hace falta, y de golpe pasás de "asistente genérico" a "experto en lo tuyo".

Qué es una skill (y qué no es)

Pensá una skill como la guía de inducción que le darías a alguien nuevo en tu equipo: el paso a paso, los formatos que usás, las reglas del negocio, los errores típicos a evitar. No es la historia de cómo resolviste algo una vez; es la técnica destilada para que se pueda repetir.

Una skill sirve para guardar cosas como:

• Flujos de trabajo — procedimientos de varios pasos para una tarea específica (armar un reporte, procesar una factura).
• Integraciones con herramientas — cómo trabajar con un formato de archivo, una API o un sistema interno.
• Conocimiento del dominio — esquemas de tu base de datos, lógica de tu negocio, políticas de tu empresa.
• Recursos reutilizables — scripts, plantillas y material de apoyo que el agente usa para no reinventar la rueda cada vez.

Lo que una skill no es: un relato del estilo "el martes pasado me pasó que...". Si está atado a un caso puntual y no lo vas a volver a usar, no es una skill.

Cuándo conviene crear una

No todo merece una skill. Creala cuando:

• La técnica no era obvia y te costó descubrirla.
• La vas a volver a usar en varios proyectos.
• El patrón aplica de forma amplia, no solo a un proyecto puntual.
• A otra persona (u otro agente) le serviría.

Evitá crear una skill para soluciones de una sola vez, para prácticas estándar que ya están bien documentadas en otro lado, o para convenciones que son específicas de un proyecto (eso va en el archivo de instrucciones del proyecto, tipo CLAUDE.md o AGENTS.md).

La estructura: el archivo SKILL.md

Toda skill vive en su propia carpeta y necesita, como mínimo, un archivo llamado SKILL.md. La estructura básica es así:

skills/
  nombre-de-tu-skill/
    SKILL.md          # el manual (obligatorio)
    archivo-extra.*   # solo si hace falta

El SKILL.md tiene dos partes:

1. El frontmatter — un bloque de metadatos arriba de todo, entre líneas de ---, escrito en YAML. Solo lleva dos campos: name y description.
2. El cuerpo — instrucciones en Markdown común. Acá va el contenido real: el procedimiento, los ejemplos, los errores a evitar.

El frontmatter: name y description

Esta parte es la más importante para que el agente encuentre tu skill. El agente lee el name y la description de todas las skills disponibles y decide cuál cargar según la tarea que tiene entre manos. Si la descripción es vaga, nunca la va a usar.

Reglas concretas:

• name: solo letras, números y guiones. Nada de paréntesis ni símbolos raros. Usá verbos en gerundio que describan la acción: procesando-facturas es mejor que gestor-facturas.
• description: escribila en tercera persona y arrancá con "Usar cuando...". Tiene que decir dos cosas: en qué situación se usa (los síntomas, el disparador) y qué hace la skill. Meté las palabras que el agente buscaría: mensajes de error, nombres de herramientas, sinónimos.

Comparemos una mala y una buena:

# MAL: vaga, no dice cuándo usarla, primera persona
description: Te ayudo con facturas

# BIEN: arranca con "Usar cuando", describe el disparador y qué hace
description: Usar cuando se necesita extraer datos de facturas en PDF
(montos, CUIT, fechas) y volcarlos a una planilla — automatiza la
lectura y el armado del resumen de gastos

Plantilla lista para copiar

Acá tenés un SKILL.md completo y funcional. Copialo, cambiá el nombre, la descripción y los pasos por los tuyos, y ya tenés tu primera skill:

---
name: nombre-de-tu-skill
description: Usar cuando [situación o síntoma que la dispara] —
[qué hace la skill y cómo ayuda, en tercera persona]
---

# Nombre de tu skill

## Resumen
Qué es esto y cuál es el principio central, en una o dos frases.

## Cuándo usarla
- Situación o síntoma 1
- Situación o síntoma 2
- Cuándo NO usarla

## Cómo usarla
1. Primer paso, concreto y accionable.
2. Segundo paso.
3. Tercer paso.

## Ejemplo
Un caso real de entrada y la salida esperada.

## Errores comunes
- Qué sale mal y cómo evitarlo.

## Recursos
Scripts, plantillas o referencias que la skill usa (si hay).

Un detalle de estilo: escribí las instrucciones en modo imperativo ("Para lograr X, hacé Y") y no en segundo plano ni con rodeos. El agente las consume mejor cuando son directas.

Divulgación progresiva: por qué tu skill no debe ser un mamotreto

Acá está la idea más importante para que esto escale. Las skills cargan información en tres niveles, y cada nivel se carga solo cuando hace falta:

1. Metadatos (name + description) — siempre presentes. Es lo que el agente lee para decidir si la skill aplica. Unas 100 palabras.
2. El cuerpo del SKILL.md — se carga recién cuando la skill se activa. Mantenelo por debajo de las ~500 palabras.
3. Recursos extra (scripts, referencias) — se cargan solo cuando el agente los necesita para la tarea puntual.

¿Por qué importa? Porque el agente tiene una memoria de trabajo limitada. Si metés todo en el SKILL.md, ocupás espacio al pedo en cada conversación. La movida es: dejá en el SKILL.md solo lo esencial del procedimiento, y mandá los detalles pesados (un esquema de base de datos largo, la documentación completa de una API) a archivos aparte que el agente lee solo cuando los precisa.

mi-skill-con-referencia/
  SKILL.md          # resumen + el flujo principal
  esquema-db.md     # 400 líneas de tablas, se carga solo si hace falta
  scripts/
    procesar.py     # código reutilizable, se ejecuta sin leerlo entero

Tres tipos de recursos extra

• scripts/ — código ejecutable (Python, Bash) para tareas que necesitan ser confiables al 100% o que reescribirías una y otra vez. Ventaja: el agente lo corre sin tener que leerlo entero.
• references/ — documentación que el agente carga bajo demanda mientras trabaja: esquemas, docs de APIs, políticas internas.
• assets/ — archivos que terminan en el resultado final, no en el razonamiento: plantillas, logos, un machete de PowerPoint, código base de un proyecto.

Regla de oro: la información vive en un solo lado. O está en el SKILL.md, o está en un archivo de referencia, pero no en los dos. Duplicar es la receta para que un día queden desincronizados.

Buenos y malos ejemplos

Para que se entienda qué separa una skill que sirve de una que estorba:

• Un ejemplo excelente le gana a diez mediocres. Poné un caso completo, que se pueda correr, comentado explicando el por qué, sacado de una situación real. No armes diez ejemplos del mismo patrón ni plantillas genéricas de rellenar-los-espacios.
• Nombres con significado. esperar-por-condicion dice qué hace; helper2 no dice nada.
• Sin relatos. "En la sesión del 3 de octubre encontramos que..." es demasiado específico y no se reutiliza. Destilá la técnica, no narres la anécdota.

Próximo paso

Elegí una tarea repetitiva que ya le explicaste tres veces a la IA y convertila en tu primera skill: copiá la plantilla de arriba, completá el name, la description y los pasos, y probala en tu próximo chat. Vas a ver la diferencia de inmediato.

Si querés que armemos juntos tus primeras skills sobre tu trabajo real — con tus procesos, tus datos y tus herramientas — agendá una llamada en /agenda y lo hacemos en vivo.