Cómo crear un Skill para agentes IA

Un Skill es una carpeta con instrucciones que los agentes IA cargan automáticamente cuando detectan que aplican.

Estructura mínima

mi-skill/
├── SKILL.md         # obligatorio
├── scripts/         # opcional
├── references/      # opcional
└── assets/          # opcional

Solo SKILL.md es requerido.

El archivo SKILL.md

---
name: mi-skill
description: Qué hace y cuándo usarlo. Sé específico.
---

# Mi Skill

## Instrucciones
- Paso 1
- Paso 2
- Paso 3

## Ejemplos
Input: ...
Output: ...

Campos obligatorios

name:

  • Máximo 64 caracteres
  • Solo minúsculas, números y guiones

description:

  • Máximo 1024 caracteres
  • Define cuándo activar el skill — esto es lo más importante

Cómo funciona en runtime

  1. Al iniciar, el agente carga solo el name y description de cada skill (~100 tokens)
  2. Si el prompt coincide con la description → lee el SKILL.md completo
  3. Si las instrucciones referencian otros archivos → los carga según necesidad

Solo entra al contexto lo que se usa. El resto queda en el filesystem.

Recursos opcionales

Puedes incluir:

  • Scripts ejecutables (scripts/validate.py)
  • Documentación adicional (REFERENCE.md)
  • Templates o assets

El agente los ejecuta directamente. El código nunca entra al contexto; solo el output.

Regla crítica

El description define cuándo se activa el skill.

Si está vago → el skill no se activa. Si está bien escrito → funciona solo.

Malo: "Procesa archivos" Bueno: "Extrae texto y tablas de PDFs. Usar cuando el usuario trabaje con archivos PDF o formularios."

TL;DR

  • Crea una carpeta con SKILL.md
  • Agrega name y description en el frontmatter
  • Escribe instrucciones claras en el cuerpo
  • El agente lo activa solo cuando aplica

En 5–10 minutos tienes un skill funcional.