Como criamos as Agent Skills da Transloadit

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos · Mostrar biografia

Dê a um agente um servidor MCP ou uma CLI e ele poderá criar Assemblies, fazer upload de arquivos e executar transformações. Mas peça a duas sessões para “codificar este vídeo em HLS” e você terá sequências diferentes de chamadas, tratamentos de erro diferentes e suposições diferentes sobre qual Template usar e onde salvar os resultados.

As Agent Skills⁠ resolvem tudo isso. São guias de procedimentos em Markdown, sob controle de versão, que especificam o que fazer, em qual ordem e como verificar o resultado.

Lançamos as Transloadit Agent Skills⁠: um pequeno catálogo de arquivos SKILL.md que abrangem fluxos de processamento de mídia, da codificação em HLS à integração com o Uppy. O catálogo evoluiu desde o lançamento, mas as lições de projeto apresentadas aqui continuam válidas.

O padrão Agent Skills

A Anthropic apresentou as Agent Skills⁠ em dezembro de 2025. Uma habilidade é um diretório com um arquivo SKILL.md: frontmatter YAML (name, description) e um corpo em Markdown com instruções. Os agentes descobrem habilidades automaticamente. O Claude Code procura em .claude/skills/, o Codex em .codex/skills/ e o Cursor em .cursor/skills/.

O formato é simples de propósito. Uma habilidade não é um novo ambiente de execução nem um framework. Ela diz ao agente o que fazer com as ferramentas que já estão no ambiente dele. Como as habilidades são arquivos comuns no seu repositório, passam por revisão de código como todo o resto.

A OpenAI adotou o mesmo formato SKILL.md em openai/skills⁠ para o Codex. A Microsoft publicou microsoft/skills⁠ para o Azure e o Copilot. A Vercel criou a CLI npx skills⁠ para instalar habilidades em mais de 35 plataformas de agentes.

O que criamos

No lançamento, o catálogo se concentrava em três categorias:

Referência

• docs-transloadit-robots: consulta offline de parâmetros e exemplos de Robot. Os agentes usam essa habilidade para elaborar ou validar o JSON de steps sem precisar adivinhar.

Transformações (processamento pontual, com download dos resultados para o ambiente local)

• transform-encode-hls-video-with-transloadit: codificação em HLS. Recebe um vídeo local e produz uma playlist de streaming adaptativo.
• transform-generate-image-with-transloadit: geração de imagens com IA. Recebe um prompt e produz um arquivo de imagem.

Integrações (gerar a estrutura de código em um aplicativo real)

• integrate-uppy-transloadit-s3-uploading-to-nextjs: adicionar o Uppy Dashboard e uploads pela Transloadit a um aplicativo Next.js, com geração de assinatura no servidor e exportação opcional para S3.
• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs: adicionar assinatura de URLs do Smart CDN a um projeto Next.js para entrega dinâmica de imagens e vídeos.

Uma habilidade de nível superior, transloadit, atua como roteador (mais detalhes abaixo). Para consultar o catálogo atual, veja o repositório e o índice de descoberta, em vez de tratar este retrato do lançamento como uma lista exaustiva.

O roteador

Em vez de despejar todo o catálogo no contexto do agente, a habilidade transloadit lê a solicitação e a encaminha para a habilidade adequada:

1. Precisa de referência (parâmetros de Robot, exemplos, sem chamadas à API) → docs-transloadit-robots
2. Precisa de uma transformação pontual (com download dos resultados para o ambiente local) → transform-*
3. Precisa de uma integração de código de ponta a ponta → integrate-*

O agente descobre o roteador automaticamente, o roteador encontra a habilidade específica, e cada habilidade tem um escopo restrito o suficiente para que o agente siga um caminho em vez de improvisar.

CLI determinística

Sem orientação, um agente pode inventar opções, escolher o Template errado ou esquecer de baixar os resultados. Vimos isso repetidamente durante o desenvolvimento. Cada habilidade transform-* especifica um comando:

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

Os Builtin Templates (builtin/encode-hls-video@latest) incorporam nossas boas práticas, então o agente não precisa compor Assembly Instructions do zero. A opção -o baixa os resultados para um diretório local em vez de deixá-los em uma URL temporária. E npx -y evita instalações globais e incompatibilidades de versão.

Testes com try-skill.ts

Uma habilidade bem escrita que produz código quebrado é pior do que nenhuma habilidade. Criamos try-skill.ts⁠ para detectar esse problema. Ele valida cada habilidade de integração de ponta a ponta:

1. Copia um projeto inicial limpo para um diretório isolado.
2. Injeta a habilidade em um agente (OpenAI Codex) executado em modo totalmente autônomo.
3. Deixa o agente aplicar a habilidade: escrever arquivos e executar comandos.
4. Executa os testes de ponta a ponta do projeto para validar o resultado.

Cada habilidade tem critérios de aceitação⁠. A habilidade de integração com o Uppy, por exemplo, precisa realmente fazer upload de um PNG pelo Uppy Dashboard e confirmar que um resultado da Transloadit é retornado. Não há mocks.

Quando os testes falhavam, tornávamos a redação mais rigorosa, adicionávamos caminhos mais explícitos e executávamos os testes novamente. Foi nisso que gastamos a maior parte do tempo de iteração. As habilidades em si parecem guias para desenvolvedores; não incluem instruções específicas dos testes.

Quando usar habilidades ou MCP

Também lançamos um Transloadit MCP Server EN (English) que dá aos agentes acesso direto às ferramentas da Transloadit em tempo de execução. A diferença é simples: o MCP fornece capacidades aos agentes (criar Assemblies, listar Templates, fazer upload de arquivos), enquanto as habilidades ensinam os agentes a usar bem essas capacidades (qual Template escolher, quais opções passar e onde salvar os resultados).

Na prática, o MCP é adequado para pipelines autônomos em que a Transloadit é executada repetidamente. As habilidades são adequadas para tarefas pontuais orientadas por uma pessoa, como configuração, geração de estrutura de código ou uma única codificação. Uma habilidade também pode instruir o agente a chamar o MCP para executar o processamento ou recorrer à CLI quando o MCP não estiver disponível.

Para ver a comparação completa e as instruções de configuração, consulte a documentação de agentes de IA.

Instalar

npx skills add transloadit/skills

Isso instala habilidades do catálogo atual. As habilidades também podem ser descobertas automaticamente por meio de /.well-known/skills/index.json, seguindo a especificação Agent Skills Discovery⁠:

npx skills add https://transloadit.com

Para instalar manualmente, clone o repositório transloadit/skills⁠ ou crie um link simbólico para ele:

Consulte a documentação de agentes de IA para ver detalhes da configuração dos clientes.

O que vem a seguir

Queremos adicionar mais habilidades de transformação (transcrição de áudio, conversão de documentos) e abranger frameworks além do Next.js. Se você precisar de um fluxo de trabalho, abra uma issue⁠.