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 si en dos sesiones le pides «codifica este video a HLS», obtendrás distintas secuencias de llamadas, distintas formas de gestionar los errores y distintas suposiciones sobre qué Template usar y dónde colocar los resultados.

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

Lanzamos las Agent Skills de Transloadit⁠: un pequeño catálogo de archivos SKILL.md que abarca flujos de trabajo de procesamiento multimedia, desde el encoding HLS hasta la integración con Uppy. El catálogo ha evolucionado desde su lanzamiento, pero estas lecciones de diseño 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: frontmatter 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 a un agente qué hacer con las herramientas que ya están disponibles en su entorno. Como las Skills son archivos simples en tu repositorio, pasan por una revisión de código como cualquier otro elemento.

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.

Lo que creamos

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

Referencia

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

Transformaciones (procesamiento puntual con resultados descargados localmente)

• transform-encode-hls-video-with-transloadit: encoding HLS. Recibe un video local y genera una lista de reproducción de 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 (generación de una estructura de código en una aplicación real)

• integrate-uppy-transloadit-s3-uploading-to-nextjs: añade Uppy Dashboard y las subidas de Transloadit a una aplicación de Next.js, con generación de firmas en el 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 de Next.js para la entrega dinámica y según demanda de imágenes y videos.

Una Skill de nivel superior, transloadit, funciona como enrutador (más información a continuación). Para consultar el catálogo actual, revisa el repositorio y el índice de descubrimiento en lugar de considerar exhaustiva esta instantánea del lanzamiento.

El enrutador

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

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

El agente detecta el enrutador automáticamente, este selecciona la Skill secundaria y cada Skill secundaria es lo suficientemente específica como para que el agente siga un único camino en vez de improvisar.

CLI determinista

Si se deja a su criterio, un agente inventará opciones, elegirá el Template incorrecto 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 prácticas recomendadas, de modo que el agente no tenga que crear Assembly Instructions desde cero. La opción -o descarga los resultados en un directorio local en vez de dejarlos en una URL temporal. Además, npx -y evita las instalaciones globales y las incompatibilidades entre versiones.

Pruebas con try-skill.ts

Una Skill que se lee bien, pero produce código defectuoso es peor que no tener ninguna. Creamos try-skill.ts⁠ para detectar ese problema. Esta herramienta valida cada Skill de integración de extremo a extremo:

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

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

Cuando las pruebas fallaban, hacíamos más precisa 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 Skills se leen como guías para desarrolladores; no incluyen instrucciones específicas para las pruebas.

Cuándo usar Agent Skills y cuándo usar MCP

También lanzamos un servidor MCP de Transloadit que brinda a los agentes acceso directo en tiempo de ejecución a las herramientas de Transloadit. La diferencia es sencilla: MCP proporciona capacidades a los agentes (crear Assemblies, enumerar Templates y subir archivos), mientras que las Agent Skills les enseñan a usar bien esas capacidades (qué Template elegir, qué opciones pasar y dónde colocar los resultados).

En la práctica, MCP es adecuado para pipelines autónomos en los que Transloadit se ejecuta repetidamente. Las Agent Skills son adecuadas para tareas puntuales dirigidas por una persona, como la configuración, la generación de una estructura inicial o un encoding único. Una Skill también puede indicarle al agente que llame a MCP para realizar la ejecución o que recurra a la CLI cuando MCP no esté disponible.

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

Instalación

npx skills add transloadit/skills

Esto instala las seis Skills. Las Skills también pueden descubrirse automáticamente mediante /.well-known/skills/index.json, de acuerdo con la especificación Agent Skills Discovery⁠:

npx skills add https://transloadit.com

Para realizar una instalación manual, clona el repositorio transloadit/skills⁠ o crea un enlace simbólico a él:

Consulta la documentación de agentes de IA para obtener instrucciones detalladas de configuración del cliente.

Próximos pasos

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