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 consegue 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 colocar os resultados.

As Agent Skills⁠ resolvem tudo isso. Elas são playbooks em markdown com controle de versão que prescrevem o que fazer, em que ordem e como verificar o resultado.

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

O padrão Agent Skills

A Anthropic apresentou as Agent Skills⁠ em dezembro de 2025. Uma skill é um diretório com um arquivo SKILL.md: frontmatter YAML (name, description) e um corpo em markdown com instruções. Os agentes descobrem as skills 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 skill não é um novo runtime nem um novo framework. Ela diz ao agente o que fazer com as ferramentas que já existem no ambiente dele. Como as skills são arquivos simples no seu repositório, elas 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 skills 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 skill para rascunhar ou validar JSON de steps sem precisar adivinhar.

Transformações (processamento pontual, com os resultados baixados localmente)

• transform-encode-hls-video-with-transloadit – codificação HLS. Entra um vídeo local, sai uma playlist de streaming adaptativo.
• transform-generate-image-with-transloadit – geração de imagens com IA. Entra um prompt, sai um arquivo de imagem.

Integrações (geram a estrutura do código em um app real)

• integrate-uppy-transloadit-s3-uploading-to-nextjs – adiciona o Uppy Dashboard e uploads da Transloadit a um app Next.js, com geração de assinaturas no lado do servidor e exportação opcional para S3.
• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs – adiciona a assinatura de URLs do Smart CDN a um projeto Next.js para entrega de imagens e vídeos sob demanda.

Uma skill transloadit de nível superior atua como roteador (mais sobre isso abaixo). Para ver o catálogo atual, consulte o repositório e o índice de descoberta em vez de tratar este retrato do lançamento como completo.

O roteador

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

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

O agente aciona o roteador automaticamente, o roteador aciona a sub-skill, e cada sub-skill é específica o bastante para que o agente siga um único caminho em vez de improvisar.

CLI determinística

Por conta própria, um agente alucina flags, escolhe o Template errado ou esquece de baixar os resultados. Vimos isso repetidas vezes durante o desenvolvimento. Cada skill transform-* prescreve um comando específico:

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 compõe as Assembly Instructions do zero. A flag -o baixa os resultados para um diretório local em vez de deixá-los atrás de uma URL temporária. E npx -y evita instalações globais e incompatibilidades de versão.

Testes com try-skill.ts

Uma skill que parece boa na leitura, mas gera código quebrado, é pior do que nenhuma skill. Criamos o try-skill.ts⁠ para detectar isso. Ele valida cada skill de integração de ponta a ponta:

1. Copiar um projeto inicial limpo para um diretório isolado.
2. Injetar a skill em um agente (OpenAI Codex) executado em modo totalmente autônomo.
3. Deixar o agente aplicar a skill: gravar arquivos e executar comandos.
4. Executar os testes de ponta a ponta do projeto sobre o resultado.

Cada skill tem critérios de aceitação⁠. A skill 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 retorna. Sem mocks.

Quando os testes falhavam, deixávamos a redação mais precisa, adicionávamos caminhos mais explícitos e rodávamos tudo de novo. A maior parte do tempo de iteração foi gasta aqui. As skills em si parecem guias escritos para desenvolvedores; nenhuma instrução específica de teste vaza para elas.

Quando usar skills ou MCP

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

Na prática, o MCP se encaixa em pipelines autônomos em que a Transloadit é executada repetidamente. As skills se encaixam em trabalhos pontuais conduzidos por pessoas, como configuração, scaffolding ou uma codificação única. Uma skill também pode instruir o agente a chamar o MCP para a execução ou a recorrer à CLI quando o MCP não estiver disponível.

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

Instalação

npx skills add transloadit/skills

Isso instala todas as seis skills. As skills também podem ser descobertas automaticamente via /.well-known/skills/index.json, seguindo a especificação Agent Skills Discovery⁠:

npx skills add https://transloadit.com

Para a instalação manual, clone o repositório transloadit/skills⁠ ou crie um link simbólico para ele:

Consulte a documentação de agentes de IA para ver a configuração detalhada de cada cliente.

O que vem a seguir

Queremos adicionar mais skills de transformação (transcrição de áudio, conversão de documentos) e cobrir outros frameworks além do Next.js. Se você precisa de algum fluxo de trabalho, abra uma issue⁠.