Una skill no es magia ni un plugin gigante: es una carpeta con un archivo de texto que le enseña a tu agente a hacer algo bien, una y otra vez. Y lo curioso es que la parte que decide si sirve o no cabe en una sola línea. Aquí te muestro cómo armar la tuya y por qué esa línea es la que manda.
[ QUÉ ES UNA SKILL, DE VERDAD ]
Una skill es una carpeta con un archivo llamado SKILL.md escrito en Markdown. Ese archivo tiene dos partes: arriba un encabezado (el frontmatter) con dos campos, name y description; y debajo, las instrucciones que quieres que el agente siga cuando use la skill. Eso es todo. El resto es opcional.
[ LA DESCRIPCIÓN MANDA ]
Aquí está el corazón del asunto. Tú no le dices al agente "usa la skill X". El agente decide solo cuándo usarla, y lo decide leyendo la descripción. Por eso la descripción no es un adorno: es el interruptor. Tiene que decir en qué casos usar la skill y, sobre todo, con las palabras que un usuario diría de verdad. A esas palabras se les llama triggers (disparadores).
description: Ayuda con documentos.
description: Usar cuando el usuario quiera resumir un PDF o un documento largo. Dispara con "resume este PDF", "sácame lo importante", "hazme un resumen del documento".
[ ANATOMÍA DE UN SKILL.md ]
Esto es un SKILL.md completo y funcional. Fíjate en los tres guiones que abren y cierran el encabezado.
---
name: resume-pdf
description: Usar cuando el usuario quiera resumir un PDF o documento largo. Dispara con "resume este PDF", "sácame lo importante", "hazme un resumen del documento".
---
# Resume PDF
1. Extrae el texto del PDF con la herramienta de lectura.
2. Devuelve las ideas principales en viñetas, máximo 8.
3. Si el documento pasa de 20 páginas, resume por secciones.
Responde siempre en español y sin relleno.¿Y qué más puede llevar la carpeta, además del SKILL.md?
- Plantillas: un formato base que la skill rellena (por ejemplo, la estructura de un correo o un informe).
- Scripts: código que hace el trabajo pesado. Opcional; muchas skills no necesitan ni uno.
- Un LICENSE: si la vas a compartir, di con qué licencia (MIT es lo típico).
- Lo mínimo, mínimo: solo el SKILL.md. Con eso ya tienes una skill que funciona.
[ DOS CAMINOS PARA CREARLA ]
Camino fácil: usa skill-creator (viene dentro de opencode-skills)
Si es tu primera vez, deja que una skill te haga la skill. skill-creator te entrevista: le dices qué quieres, te hace un par de preguntas para afinar, y arma la carpeta, valida el SKILL.md y hasta te lo empaqueta. Ideal para agarrar la lógica sin pelear con la estructura.
$ quiero una skill que me resuma PDFs De una. ¿La salida la prefieres en viñetas, en párrafo o las dos?$ viñetas, máximo 8 Listo. ¿Te la creo, la valido y te la dejo empaquetada?# arma la carpeta y revisa que la descripción tenga triggers por ti
Camino a mano: cuando ya le agarraste el gusto
Ponle el nombre de tu skill, en minúsculas y con guiones: resume-pdf. Ese mismo nombre va después en el campo name.
Frontmatter con name y description (aquí es donde vives o mueres: mete los triggers reales). Debajo, las instrucciones: concretas, cortas, en el orden en que quieres que pasen las cosas.
¿Necesita una plantilla o un script? Agrégalo a la carpeta y menciónalo en las instrucciones. ¿No lo necesita? Perfecto, déjalo con solo el SKILL.md.
Pídele al agente algo que debería disparar la skill. ¿No se activó? Casi siempre es la descripción, no las instrucciones. Ajusta los triggers y vuelve a probar.
[ LA PRUEBA DE FUEGO ]
La forma correcta de probar no es decir "usa la skill". Eso hace trampa. Pídele la tarea como se la pedirías cualquier día, y mira si la skill se enciende sola. Si arranca sin que la nombres, tu descripción quedó bien hecha.
# nada de "usa la skill resume-pdf". Pídelo natural:$ resume este PDF y sácame lo importante Leyendo el documento… listo, aquí van 8 puntos clave:# si la cargó sola, los triggers hicieron su trabajo
- Una skill es una carpeta con un SKILL.md: frontmatter (name + description) arriba, instrucciones abajo.
- La descripción manda: es lo que el agente lee para decidir cuándo usar la skill. Métele los triggers que la gente diría de verdad.
- Descripción vaga = skill que nunca se activa, por muy buenas que sean las instrucciones.
- El agente carga el detalle solo cuando lo necesita (revelación progresiva). Por eso no gastas contexto de más.
- Instrucciones cortas y concretas, no un ensayo. Una skill, una tarea.
- Empieza con skill-creator si es tu primera; hazla a mano cuando ya la tengas clara. Y siempre: prueba con casos reales e itera.