Cómo crear Skills eficientes para agentes de IA (con plantillas para copiar)

En el blog anterior vimos qué es un Skill. Ahora viene la pregunta que importa de verdad: ¿cómo escribes uno que el agente sí use, y que haga bien la tarea la primera vez?

La mayoría de los Skills malos no fallan por falta de esfuerzo. Fallan por exceso: demasiadas instrucciones, demasiadas opciones, una descripción tan genérica que el agente nunca sabe cuándo abrirla. Vamos a construir uno de verdad, con las reglas que Anthropic documentó para esto — y con plantillas que puedes copiar tal cual, aunque no programes.

Primero: no diseñes el Skill. Cápturalo.

Este es el error de origen más común: sentarte a "diseñar" un Skill perfecto antes de haberlo necesitado ni una vez.

La forma correcta es al revés:

1. Haces la tarea sin Skill, a mano, dos o tres veces.
2. Te fijas en qué le explicas al agente cada vez — ese es el patrón que se repite.
3. Le pides al agente que convierta eso en un Skill.
4. Lo pruebas, lo recortas, lo vuelves a probar.

Anthropic lo dice así, literal: el proceso te ayuda a descubrir qué contexto necesita realmente el agente, en vez de intentar adivinarlo de antemano. Nada de sentarte a imaginar todos los casos posibles — eso es lo que hace que un Skill termine con 300 líneas que nadie lee.

La description lo es todo

Esto decide si tu Skill se activa o se queda dormido en la carpeta para siempre. El agente no lee el Skill completo al arrancar — solo lee su nombre y su descripción. Si la descripción no es clara, nunca lo va a abrir.

Regla 1 — Tercera persona, no segunda.

❌ description: Te ayudo a procesar archivos de Excel ✅ description: Procesa archivos de Excel y genera reportes

Regla 2 — Di qué hace Y cuándo usarlo.

❌ description: Ayuda con documentos ✅ description: Extrae texto y tablas de PDFs, rellena formularios, combina documentos. Úsalo cuando se trabaje con archivos PDF o el usuario mencione formularios, contratos o extracción de datos.

Regla 3 — Sé un poco insistente. El agente tiende a no activar un Skill salvo que el match sea obvio. Anthropic recomienda literalmente empujarlo un poco:

"...Usa este skill siempre que el usuario mencione dashboards, visualización de datos, métricas internas, o quiera mostrar cualquier tipo de dato de la empresa — incluso si no pide explícitamente un 'dashboard'."

Plantilla para copiar (encabezado de cualquier Skill)

---
name: nombre-del-skill
description: [Qué hace en una frase]. Úsalo cuando [disparadores concretos: palabras, tipos de archivo, situaciones], incluso si el usuario no lo pide con esas palabras exactas.
---

Los 3 niveles de libertad (y por qué casi nadie los usa bien)

No todos los Skills deben escribirse igual. Depende de qué tan peligroso es equivocarse.

Nivel	Cuándo usarlo	Cómo se escribe
Alto	Hay varias formas válidas de resolverlo, depende del contexto	Instrucciones en texto, guía general
Medio	Hay un patrón preferido, pero se permite variación	Pseudocódigo o plantilla con parámetros
Bajo	Un error sale caro o es irreversible	Pasos exactos, sin margen de interpretación

Anthropic lo explica con una imagen simple: pensar en el agente como alguien caminando por un puente angosto con un precipicio a cada lado (ahí no le das opciones, le das el único camino seguro) versus caminando por un campo abierto sin peligros (ahí le das dirección general y confías en su criterio).

Acá van tres plantillas reales — una por nivel, y ninguna de programación, para que veas que esto no es solo para escribir código.

---

Plantilla 1 — Libertad alta: revisar un contrato de servicio

---
name: revision-contrato-servicio
description: Revisa contratos de servicio o acuerdos con clientes antes de firmarlos, señalando cláusulas de riesgo. Úsalo cuando el usuario comparta un contrato, una propuesta de acuerdo, o pregunte "¿esto está bien firmarlo?".
---

# Revisión de contrato de servicio

Cuando revises un contrato, evalúa estos puntos y da tu opinión con criterio — no hay una única forma correcta de leerlo, usa tu juicio según el contexto del negocio:

- ¿Hay cláusula de cancelación? ¿Con cuánto preaviso?
- ¿Quién es dueño del trabajo entregado una vez pagado?
- ¿Existe penalización por pago tardío del cliente?
- ¿El alcance del trabajo está definido o es ambiguo ("y otras tareas relacionadas")?
- ¿Hay límite de revisiones incluidas antes de cobrar extra?

Señala los puntos de riesgo en orden de importancia, no en el orden en que aparecen en el documento. Si algo es ambiguo, dilo explícitamente — no asumas la interpretación más favorable para ninguna de las partes.

---

Plantilla 2 — Libertad media: reporte semanal a un cliente

---
name: reporte-semanal-cliente
description: Genera el reporte semanal de avance para clientes a partir de las tareas completadas. Úsalo cuando el usuario pida "arma el reporte de esta semana" o pegue una lista de tareas hechas.
---

# Reporte semanal de avance

Estructura por defecto (puedes ajustar el orden si el cliente lo pidió distinto):

1. **Resumen** — 2-3 líneas de lo más importante de la semana.
2. **Completado** — lista de tareas terminadas, en lenguaje de cliente (no jerga interna).
3. **En progreso** — qué sigue en curso y fecha estimada.
4. **Bloqueos** — solo si existen; no inventes una sección vacía.
5. **Próxima semana** — 2-3 prioridades.

Tono: directo y sin relleno. Si una tarea se retrasó, dilo sin rodeos y con la nueva fecha — no lo escondas en el medio del texto.

---

Plantilla 3 — Libertad baja: cierre de caja diario (acción crítica)

---
name: cierre-caja-diario
description: Ejecuta el checklist exacto de cierre de caja al final del día. Úsalo únicamente cuando el usuario diga explícitamente "cerrar caja" o "hacer el corte del día".
---

# Cierre de caja diario

Sigue estos pasos EN ESTE ORDEN. No agregues pasos ni cambies el orden aunque parezca más eficiente de otra forma:

1. Suma el efectivo físico en caja.
2. Compara contra el total del sistema de ventas del día.
3. Si hay diferencia, repórtala como "Diferencia: +/- $X" — nunca ajustes el número para que cuadre.
4. Registra el total final en la planilla de cierre.
5. Marca el día como cerrado. Una vez cerrado, no se puede reabrir sin autorización del dueño.

Este proceso no admite variaciones. Si algo no cuadra, repórtalo — no lo "arregles" por tu cuenta.

---

Nota lo que cambia entre las tres: la de libertad alta le da criterio al agente ("usa tu juicio"), la de libertad baja se lo quita a propósito ("no agregues pasos"). Elegir mal el nivel es la forma más común de que un Skill falle: demasiado rígido para tareas que necesitan criterio, o demasiado libre para tareas donde un error cuesta caro.

La estructura de carpetas (cuándo necesitas más que un solo archivo)

Para la mayoría de los Skills, un solo SKILL.md alcanza. Cuando empieza a crecer más allá de las ~500 líneas, se separa así:

mi-skill/
  SKILL.md          ← el núcleo: cuándo usarlo, pasos principales
  references/        ← el agente los lee solo si los necesita
    casos-especiales.md
  scripts/            ← código que se ejecuta, no se lee
    validar.py
  assets/             ← plantillas, logos, archivos base
    plantilla.docx

La regla de oro: el SKILL.md referencia a references/casos-especiales.md por nombre, y el agente decide si vale la pena abrirlo. Si tu Skill de reportes tiene una sección larga de "qué hacer si el cliente pidió un formato especial", esa sección se va a references/, no se queda en el archivo principal.

Errores que hacen que un Skill se sienta "raro"

• Explicarle al agente lo que ya sabe. No necesitas decirle "un PDF es un documento portátil que...". Escribe solo lo que el agente no sabría por defecto: tus convenciones, tus excepciones, tus casos raros.
• Description demasiado amplia. Si dice "ayuda con cualquier tarea de marketing", se va a activar cuando no debe y va a competir con otros Skills. Sé específico.
• Demasiadas opciones sin un default. "Puedes usar el formato A, B o C" deja al agente adivinando. Da un default claro y menciona la excepción aparte: "usa el formato A; si el cliente pidió PDF, usa B."
• Mayúsculas tipo SIEMPRE/NUNCA sin explicar el porqué. Es mejor explicar la razón — así el agente sabe razonar en los casos raros que no anticipaste.

Pruébalo antes de confiar en él

No hace falta un sistema complejo. Antes de dar por bueno un Skill, arma 3 escenarios de prueba: uno típico, uno raro, y uno donde el Skill no debería activarse. Corre los tres. Si falla alguno, ajusta la description o los pasos — no agregues más texto "por si acaso", eso empeora el problema.

Una advertencia de seguridad que no puedes saltarte

Un Skill le da al agente instrucciones que sigue casi al pie de la letra. Si instalas uno de una fuente que no conoces, estás confiando en ese texto tanto como confiarías en un paquete de npm sin revisar. La recomendación de Anthropic es simple: usa Skills que tú mismo escribiste, o de fuentes verificadas — y si vas a instalar uno de terceros, léelo completo antes, prestando atención a cualquier instrucción que le pida al agente conectarse a un sitio externo o mandar información fuera del proyecto.

En OpenCode esto se controla por permisos, sin tener que confiar a ciegas:

{
  "permission": {
    "skill": {
      "*": "allow",
      "experimental-*": "ask"
    }
  }
}

Con esto, cualquier Skill que empiece con experimental- te pide confirmación antes de cargarse.

Nota para quien viene de OpenCode

Si ya armaste Skills para Claude Code, no tienes que reescribirlos: OpenCode busca automáticamente en .claude/skills/ además de su propia carpeta .opencode/skills/. El mismo SKILL.md, sin tocarle una línea, funciona en ambos.