Cómo creamos las Agent Skills de Transloadit

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Dale a un agente un servidor MCP o una CLI y podrá crear Assemblies, subir archivos y ejecutar transformaciones. Pero pide en dos sesiones que «codifique este video a HLS» y obtendrás distintas secuencias de llamadas, diferentes formas de manejar errores y distintas suposiciones sobre qué Template usar y dónde guardar los resultados.

Las Agent Skills⁠ resuelven todo eso. Son guías de procedimientos en Markdown con control de versiones que indican qué hacer, en qué orden y cómo verificar el resultado.

Lanzamos Transloadit Agent Skills⁠: un pequeño catálogo de archivos SKILL.md que cubren flujos de procesamiento multimedia, desde la codificación HLS hasta la integración con Uppy. El catálogo ha evolucionado desde su lanzamiento, pero las lecciones de diseño que compartimos aquí siguen siendo válidas.

El estándar Agent Skills

Anthropic presentó Agent Skills⁠ en diciembre de 2025. Una Skill es un directorio con un archivo SKILL.md: metadatos YAML (name, description) y un cuerpo en Markdown con instrucciones. Los agentes descubren las Skills automáticamente. Claude Code busca en .claude/skills/, Codex en .codex/skills/ y Cursor en .cursor/skills/.

El formato es sencillo a propósito. Una Skill no es un nuevo entorno de ejecución ni un framework. Le indica al agente qué hacer con las herramientas que ya tiene en su entorno. Como las Skills son archivos comunes de tu repositorio, pasan por revisión de código como todo lo demás.

OpenAI adoptó el mismo formato SKILL.md en openai/skills⁠ para Codex. Microsoft publicó microsoft/skills⁠ para Azure y Copilot. Vercel creó la CLI npx skills⁠ para instalar Skills en más de 35 plataformas de agentes.

Qué creamos

En el lanzamiento, el catálogo se centraba en tres categorías:

Referencia

• docs-transloadit-robots: consulta sin conexión de parámetros de Robot y ejemplos. Los agentes la usan para redactar o validar el JSON de steps sin tener que adivinar.

Transformaciones (procesamiento puntual, con resultados descargados localmente)

• transform-encode-hls-video-with-transloadit: codificación HLS. Recibe un video local y genera una lista de reproducción para streaming adaptativo.
• transform-generate-image-with-transloadit: generación de imágenes con IA. Recibe un prompt de texto y genera un archivo de imagen.

Integraciones (generan código base en una aplicación real)

• integrate-uppy-transloadit-s3-uploading-to-nextjs: añade Uppy Dashboard y subidas mediante Transloadit a una aplicación Next.js, con generación de firmas del lado del servidor y exportación opcional a S3.
• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs: añade la firma de URL de Smart CDN a un proyecto Next.js para entregar imágenes y videos de forma dinámica, según se necesiten.

Una Skill de nivel superior, transloadit, actúa como enrutador (más detalles abajo). Para conocer el catálogo actual, consulta el repositorio y el índice de descubrimiento; esta descripción del catálogo en el lanzamiento no refleja de forma exhaustiva el catálogo actual.

El enrutador

En lugar de volcar todo el catálogo en el contexto del agente, la Skill transloadit lee la solicitud y la dirige a la Skill adecuada:

1. Necesitas material de referencia (parámetros de Robots, ejemplos, sin llamadas a la API) → docs-transloadit-robots
2. Necesitas una transformación puntual (descargar los resultados localmente) → transform-*
3. Necesitas una integración de código de extremo a extremo → integrate-*

El agente descubre el enrutador automáticamente, el enrutador encuentra la Skill especializada y cada una tiene un alcance lo bastante limitado para que el agente siga una ruta en lugar de improvisar.

CLI determinista

Sin instrucciones concretas, un agente inventará opciones, elegirá el Template equivocado u olvidará descargar los resultados. Lo vimos repetidamente durante el desarrollo. Cada Skill transform-* prescribe un comando específico:

npx -y @transloadit/node assemblies create \
  --template builtin/encode-hls-video@latest \
  -i ./input.mp4 \
  -o ./out/ \
  -j

Los Builtin Templates (builtin/encode-hls-video@latest) incorporan nuestras mejores prácticas, por lo que el agente no crea las Assembly Instructions desde cero. La opción -o descarga los resultados en un directorio local en lugar de dejarlos en una URL temporal. Y npx -y evita las instalaciones globales y las incompatibilidades de versiones.

Pruebas con try-skill.ts

Una Skill que se lee bien, pero produce código que no funciona, es peor que no tener ninguna. Creamos try-skill.ts⁠ para detectar esos problemas. Valida cada Skill de integración de extremo a extremo:

1. Copia un proyecto inicial limpio en un directorio aislado.
2. Incorpora la Skill a un agente (OpenAI Codex) que se ejecute en modo completamente autónomo.
3. Deja que el agente aplique la Skill: escriba archivos y ejecute comandos.
4. Ejecuta las pruebas de extremo a extremo del proyecto sobre el resultado.

Cada Skill tiene criterios de aceptación⁠. La Skill de integración con Uppy, por ejemplo, debe subir realmente un PNG mediante Uppy Dashboard y confirmar que se recibe un resultado de Transloadit. Sin simulaciones.

Cuando las pruebas fallaban, precisábamos la redacción, añadíamos rutas más explícitas y volvíamos a ejecutarlas. La mayor parte del tiempo de iteración se dedicó a esto. Las propias Skills se leen como guías para desarrolladores; no incluyen instrucciones específicas para las pruebas.

Cuándo usar Skills frente a MCP

También lanzamos un servidor MCP de Transloadit que da a los agentes acceso directo a las herramientas de Transloadit durante la ejecución. La diferencia es sencilla: MCP proporciona capacidades a los agentes (crear Assemblies, listar Templates, subir archivos), mientras que las Skills les enseñan a usarlas bien (qué Template elegir, qué opciones pasar y dónde guardar los resultados).

En la práctica, MCP encaja en pipelines autónomos en los que Transloadit se ejecuta repetidamente. Las Skills encajan en tareas puntuales dirigidas por personas, como la configuración, la generación de código base o una codificación única. Una Skill también puede indicar al agente que llame a MCP para ejecutar la tarea o que recurra a la CLI cuando MCP no esté disponible.

Para consultar la comparación completa y las instrucciones de configuración, consulta la documentación de agentes de IA.

Instala

npx skills add transloadit/skills

Esto instala Skills del catálogo actual. Las Skills también se pueden descubrir automáticamente mediante /.well-known/skills/index.json, siguiendo la especificación Agent Skills Discovery⁠:

npx skills add https://transloadit.com

Para instalarlas manualmente, clona el repositorio transloadit/skills⁠ o crea un enlace simbólico a él:

Consulta la documentación de agentes de IA para conocer los detalles de configuración del cliente.

Qué sigue

Queremos añadir más Skills de transformación (transcripción de audio, conversión de documentos) y cubrir otros frameworks además de Next.js. Si necesitas un flujo de trabajo, abre una incidencia⁠.