Ya tenía tiempo queriendo escribir en este blog con varios temas e ideas en la cabeza, este primer tema que seleccioné, es relacionado con los skills que se utilizan por agentes de IA que operan en la terminal, como Gemini CLI, Claude Code o Codex. Para este post asumiré que ya tienes una idea general de qué son estas herramientas y para qué sirven. En caso de que no, puedes buscarlas en la red y seguro encontrarás rápidamente una introducción y para qué se utilizan.
Para este post tomaré como referencia el formato abierto Agent Skills, aunque algunos detalles de su implementación pueden variar entre herramientas.
Pero, ¿para qué un skill?
La primera vez que yo escuché sobre ellos, me pregunté, pero si se supone que estas herramientas ya son inteligentes y tienen super conocimientos generales, ¿por qué necesitamos darles además instrucciones adicionales para realizar ciertas tareas?
Ok, una forma de verlo es imaginando este escenario. Cuando trabajamos en algo contamos con los siguientes elementos a grandes rasgos:
- Una descripción de la tarea que tenemos que hacer.
- Nosotros como ejecutores de la tarea.
- Finalmente, una guía o conocimiento de cómo podemos ejecutar la tarea de la mejor manera posible y qué herramientas utilizar.
Podríamos decir que el punto 3 es opcional, pero si no tenemos esa guía podríamos estar improvisando cada vez que tenemos ese tipo de tarea particular. Además este punto 3 podría indicarnos atajos o recomendaciones de dónde encontrar herramientas que nos pueden servir para hacerlo mejor, más rápido y de una forma consistente. Pues bien cada uno de esos puntos se pueden ver de la siguiente forma cuando trabajamos con agentes de IA:
- La descripción de la tarea podría ser lo que entendemos como el prompt, junto con el contexto que proporcionamos.
- En este punto 2 (el ejecutor) sería el agente o sistema agéntico, por ejemplo, Gemini CLI, Claude Code o Codex. También puede ser un sistema agéntico orquestado mediante un framework como LangGraph, al que se le haya incorporado un mecanismo para descubrir y utilizar skills. Este utiliza un LLM (Large Language Model o Modelo Grande del Lenguaje), herramientas, contexto y un entorno de ejecución para realizar la tarea.
- Finalmente, este punto 3 sería el skill, que le indica al agente o sistema agéntico cómo abordar cierto tipo de trabajo de manera consistente.
Podemos concluir de manera general que un skill para un agente de IA es: un paquete reutilizable que contiene instrucciones y que también puede incluir documentos de referencia, scripts, plantillas y otros recursos para ejecutar una tarea de manera consistente.
Super, entonces, le doy todo y ya está...
Si ya habías oído sobre los skills, podrías estarte preguntando, ok para que me ayude, le doy un bonche de documentos donde explique cómo hacer todo lo que yo hago y ya está, ahí quedaron mis skills; y la respuesta es sí pero no exactamente así, para los skills se recomienda utilizar una estructura, y seguro te preguntarás, ¿por qué?
Una de las principales razones para utilizar esta estructura es por algo que se conoce como ventana de contexto (context window). La ventana de contexto es la cantidad limitada de información - expresada en tokens - que el modelo puede considerar durante una ejecución. Vamos a hacer una comparación simplificada de lo que sucede, ya que es algo que en cierta forma nos pasa también a nosotros.
Normalmente cuando tenemos algo que hacer utilizamos nuestra memoria de trabajo, esto es, mientras realizamos una tarea tenemos que acordarnos de cosas mientras la ejecutamos, por ejemplo, imagina una persona trabajando en un almacén, le podrá ser muy sencillo recordar los números del código de barras, tal vez de algunos que acaba de registrar, pero tal vez ya olvidó aquellos no tan comunes del día anterior. Bien, imagina que simplemente le decimos a la persona que tiene que leer todos los números de todos los productos antes de empezar a trabajar y luego empezar a trabajar. Esto aunque es posible, no sería lo más eficiente. Una mejor estrategia es decirle, te doy esta herramienta o documento donde puedes encontrar el número de código de barras de un producto cada vez que lo necesites. De manera muy simplificada, esta es una de las ideas detrás de los skills: en lugar de cargar desde el principio toda la información que el agente podría llegar a necesitar, le proporcionamos una forma organizada de localizarla y consultarla cuando resulte relevante.
Diversas evaluaciones han demostrado que el rendimiento de los modelos puede degradarse a medida que aumenta la cantidad de información en el contexto, incluso antes de alcanzar su límite máximo, especialmente cuando la información es extensa y está mezclada con contenido irrelevante o difícil de localizar.
Aunque los modelos actuales cada vez pueden manejar ventanas de contexto más grandes, esto no quiere decir que toda la información se vaya a utilizar con la misma eficacia. Cuando el contexto crece demasiado puede aumentar el costo y la latencia, y también puede resultar más difícil localizar o utilizar correctamente la información relevante.
Además de manera análoga a nuestro ejemplo, la ventana de contexto es también limitada. Para trabajar durante periodos prolongados, algunos sistemas eliminan información anterior o utilizan mecanismos de compactación que conservan el estado más relevante utilizando menos tokens. Sin embargo, durante este proceso podrían perderse algunos detalles, por lo que sigue siendo conveniente evitar cargar información innecesaria desde el principio.
Entonces, cuando ponemos un skill a disposición de un agente, es como decirle: "Hey agente, cuando trabajes este tipo de tarea, aquí puedes encontrar instrucciones y recursos que podrían ayudarte". Inicialmente, el agente solo recibe algunos metadatos del skill, esto es básicamente su nombre y descripción. Análogamente a nuestro ejemplo, es como si únicamente supiera que tiene a disposición una guía de productos y sus códigos de barras. No necesita leer toda la lista desde el principio; solo sabe que existe y que puede consultarla. Si detecta que el skill puede ser relevante para la tarea, carga las instrucciones de su archivo SKILL.md y posteriormente consulta documentos de referencia, scripts o utiliza otros recursos conforme los necesite. Este proceso se conoce como divulgación progresiva (progressive disclosure).
Estructura de un skill
La estructura de un skill es la siguiente:
nombre-del-skill/
├── SKILL.md # Obligatorio
├── references/ # Documentación de apoyo, opcional
├── scripts/ # Código ejecutable, opcional
└── assets/ # Plantillas y otros recursos, opcional
SKILL.md
Vamos que lleva esto, el primero de ellos es el archivo SKILL.md:
______________________________________________________________________
---
name: validating-evidences
description: Validates evidence and generates a report. Use when reviewing evidence packages.
---
# Instructions
When you use this skill:
1. Review the input entry
2. Follow this procedure
3. Validate the result
4. Show the output in this format
For more detail rules, review:
- `references/rules.md`
For validation, execute:
- `scripts/validation.py`
______________________________________________________________________
El nombre solo puede contener letras minúsculas, números y guiones; no puede empezar o terminar con un guión ni contener guiones consecutivos. Además, debe coincidir con el nombre de la carpeta, máximo 64 caracteres, y aunque no es un requisito en algunas guías se recomienda utilizar gerundio (por ejemplo, processing-pdfs).
En el caso de la descripción, contiene la explicación de que hace el skill y cuándo conviene utilizarlo. Normalmente se recomienda redactar en tercera persona, contener términos clave y contextos de activación, máximo 1024 caracteres.
De manera general, se recomienda que el archivo no pase de las 500 líneas. No es obligatorio escribirlo en inglés; sin embargo, hacerlo puede facilitar su reutilización y colaboración entre equipos internacionales. Además, algunas evaluaciones multilingües han encontrado diferencias de rendimiento entre idiomas, particularmente entre el inglés y los idiomas con menos datos disponibles. Esto depende del modelo, el idioma y el tipo de tarea, por lo que escribir un skill en inglés no es una restricción ni un requisito técnico.
references/
Esta carpeta es opcional y aquí podríamos tener información de apoyo:
references/
├── rules.md
├── api-specification.yaml
└── evidence-schema.json
scripts/
En esta carpeta se pueden encontrar scripts que puedan ser de utilidad para realizar la tarea, por ejemplo:
scripts/
├── validation.py
├── check_evidence.js
└── generate_report.sh
No necesariamente deben estar en un lenguaje específico (como Python por ejemplo), tampoco todos en el mismo lenguaje, pero sí conviene incluir en el SKILL.md las instrucciones para que el agente sepa cómo utilizarlos.
Esta carpeta es opcional; no todos los skill necesitan tener scripts.
assets/
La idea es que esta carpeta contenga archivos que se utilizan para generar el resultado, como formatos, plantillas, imágenes, etc.
assets/
├── report-template.docx
├── results-template.xlsx
└── logo.png¿Y quién o quienes los hacen?
Ok, aquí viene lo más interesante de todo esto: podemos pedirle a un agente de IA que nos ayude a construir el skill. Podemos darle los lineamientos generales, el objetivo y algunos ejemplos, y este lo va a generar con la estructura recomendada. Esto no quiere decir que lo creará 100% como lo necesitamos. Si llegaste hasta aquí ahora ya conoces la estructura de un skill, por lo que podemos revisar el contenido, instrucciones, scripts y demás recursos, para validar que cumplan con lo que necesitamos.
Pero espera, esto no termina aquí. Una estrategia interesante consiste en separar la creación y la prueba del skill entre dos agentes. Por ejemplo, un agente A construye el skill, y otro agente B lo utiliza. Si en los resultados encontramos errores o cosas por mejorar, esto se documenta y se lo pasamos al agente A para que ajuste el Skill. Posteriormente se lo damos de nuevo al B y, como puedes ver aquí tenemos ese ciclo de mejora para nuestros skills.
Elaboración propia basada en el ciclo de creación, evaluación y mejora de skills.
¿Dónde puedo compartir mis skills?
Bueno, lo simple es crear un repositorio, por ejemplo en GitHub, y compartirlos desde ahí. Sin embargo, uno de los directorios más populares es https://www.skills.sh/ operado por Vercel. Este sitio permite explorar skills para diferentes agentes, como Claude Code, Codex y Gemini, y también consultar cuáles son los más utilizados, cuáles provienen de organizaciones reconocidas y cuáles cuentan con alguna auditoría de seguridad.
Los skills alojados en GitHub pueden aparecer automáticamente en este directorio cuando los usuarios los instalan mediante el comando:
$ npx skills add <owner/repo>
ejemplo:
$ npx skills add omaryahir/el-skill
⚠ Importante - Nota de Seguridad: Como te puedes dar cuenta podemos consumir skills creados por otras personas u organizaciones. Antes de utilizar cualquier skill, es importante revisar sus instrucciones, scripts y demás recursos, ya que podrían indicarle al agente que ejecute código o acceda a archivos del entorno para realizar acciones no deseadas o incluso inseguras.
Por el momento, hasta aquí llegamos, espero te sea de utilidad!
Referencias:
Lost in the Middle: How Language Models Use Long Contexts
Degradación del rendimiento con entradas de contexto extensas.
