Comment nous avons créé les Agent Skills de Transloadit

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Donnez à un agent un serveur MCP ou une CLI, et il pourra créer des Assemblies, téléverser des fichiers et effectuer des transformations. Mais demandez à deux sessions « encodez cette vidéo en HLS », et vous obtiendrez des séquences d’appels différentes, une gestion des erreurs différente et des hypothèses différentes sur le Template à utiliser et l’emplacement des résultats.

Les Agent Skills⁠ résolvent tous ces problèmes. Ce sont des guides opérationnels en Markdown, placés sous contrôle de version, qui précisent quoi faire, dans quel ordre et comment vérifier le résultat.

Nous avons publié les Transloadit Agent Skills⁠ : un petit catalogue de fichiers SKILL.md couvrant des processus de traitement multimédia, de l’encodage HLS à l’intégration d’Uppy. Le catalogue a évolué depuis son lancement, mais les enseignements de conception présentés ici restent valables.

Le standard Agent Skills

Anthropic a présenté les Agent Skills⁠ en décembre 2025. Un Skill est un répertoire contenant un fichier SKILL.md : un en-tête YAML (name, description) et un corps en Markdown contenant les instructions. Les agents découvrent automatiquement les Skills. Claude Code les recherche dans .claude/skills/, Codex dans .codex/skills/, Cursor dans .cursor/skills/.

Le format est volontairement simple. Un Skill n’est pas un nouvel environnement d’exécution ni un framework. Il indique à un agent comment utiliser les outils déjà présents dans son environnement. Comme les Skills sont de simples fichiers dans votre dépôt, ils passent par la revue de code comme le reste.

OpenAI a adopté le même format SKILL.md dans openai/skills⁠ pour Codex. Microsoft a publié microsoft/skills⁠ pour Azure et Copilot. Vercel a créé la CLI npx skills⁠ pour installer des Skills sur plus de 35 plateformes d’agents.

Ce que nous avons créé

Au lancement, le catalogue s’articulait autour de trois catégories :

Documentation de référence

• docs-transloadit-robots – consultation hors ligne des paramètres et des exemples de Robot. Les agents l’utilisent pour rédiger ou valider le JSON steps sans rien deviner.

Transformations (traitement ponctuel, résultats téléchargés localement)

• transform-encode-hls-video-with-transloadit – encodage HLS. Une vidéo locale en entrée, une liste de lecture pour la diffusion adaptative en sortie.
• transform-generate-image-with-transloadit – génération d’images par IA. Une consigne textuelle en entrée, un fichier image en sortie.

Intégrations (génération d’une base de code dans une véritable application)

• integrate-uppy-transloadit-s3-uploading-to-nextjs – ajouter Uppy Dashboard et les téléversements Transloadit à une application Next.js, avec génération de signatures côté serveur et export S3 facultatif.
• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs – ajouter la signature des URL du Smart CDN à un projet Next.js pour la livraison dynamique d’images et de vidéos à la demande.

Un Skill principal transloadit sert de routeur (nous y revenons ci-dessous). Pour consulter le catalogue actuel, référez-vous au dépôt et à l’index de découverte, car cet aperçu du lancement n’est pas exhaustif.

Le routeur

Au lieu de charger tout le catalogue dans le contexte de l’agent, le Skill transloadit lit la demande et l’oriente vers le Skill approprié :

1. Vous avez besoin de documentation de référence (paramètres de Robots, exemples, sans appels à l’API) → docs-transloadit-robots
2. Vous avez besoin d’une transformation ponctuelle (télécharger les résultats localement) → transform-*
3. Vous avez besoin d’une intégration de code de bout en bout → integrate-*

L’agent découvre automatiquement le routeur, le routeur sélectionne le sous-Skill adapté à la demande, et chaque sous-Skill est suffisamment ciblé pour que l’agent suive un seul chemin au lieu d’improviser.

CLI déterministe

Livré à lui-même, un agent inventera des options, choisira le mauvais Template ou oubliera de télécharger les résultats. Nous l’avons constaté à plusieurs reprises pendant le développement. Chaque Skill transform-* prescrit une commande précise :

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

Les Builtin Templates (builtin/encode-hls-video@latest) intègrent nos bonnes pratiques : l’agent n’a donc pas à composer des Assembly Instructions à partir de zéro. L’option -o télécharge les résultats dans un répertoire local au lieu de les laisser accessibles par une URL temporaire. Et npx -y évite les installations globales et les incompatibilités de versions.

Tester avec try-skill.ts

Un Skill agréable à lire, mais qui produit du code défectueux, est pire que l’absence de Skill. Nous avons créé try-skill.ts⁠ pour détecter ce problème. Cet outil valide chaque Skill d’intégration de bout en bout :

1. Copier un projet de démarrage propre dans un répertoire isolé.
2. Injecter le Skill dans un agent (OpenAI Codex) fonctionnant en mode entièrement autonome.
3. Laisser l’agent appliquer le Skill : écrire des fichiers, exécuter des commandes.
4. Exécuter les tests de bout en bout du projet sur le résultat.

Chaque Skill a des critères d’acceptation⁠. Le Skill d’intégration Uppy, par exemple, doit réellement téléverser un PNG via Uppy Dashboard et confirmer qu’un résultat Transloadit est renvoyé. Aucune simulation.

Lorsque les tests échouaient, nous précisions la formulation des instructions, ajoutions des chemins plus explicites et relancions les tests. C’est là que nous avons consacré l’essentiel du temps d’itération. Les Skills eux-mêmes se lisent comme des guides pour développeurs ; aucune instruction spécifique aux tests ne s’y glisse.

Quand utiliser les Skills ou MCP

Nous avons également publié un serveur MCP Transloadit EN (English) qui donne aux agents un accès direct aux outils Transloadit à l’exécution. La différence est simple : MCP fournit aux agents des capacités (créer des Assemblies, lister des Templates, téléverser des fichiers), tandis que les Skills leur enseignent comment bien les utiliser (quel Template choisir, quelles options passer, où placer les résultats).

En pratique, MCP convient aux chaînes de traitement autonomes dans lesquelles Transloadit est exécuté à répétition. Les Skills conviennent aux tâches ponctuelles pilotées par une personne, comme la configuration, la génération d’une base de code ou un encodage unique. Un Skill peut aussi indiquer à l’agent d’appeler MCP pour l’exécution ou de se rabattre sur la CLI si MCP est indisponible.

Pour la comparaison complète et les instructions de configuration, consultez la documentation sur les agents IA.

Installer

npx skills add transloadit/skills

Cette commande installe les Skills du catalogue actuel. Les Skills peuvent aussi être découverts automatiquement via /.well-known/skills/index.json, conformément à la spécification Agent Skills Discovery⁠ :

npx skills add https://transloadit.com

Pour une installation manuelle, clonez le dépôt transloadit/skills⁠ ou créez un lien symbolique vers celui-ci :

Consultez la documentation sur les agents IA pour obtenir les détails de configuration des clients.

La suite

Nous souhaitons ajouter d’autres Skills de transformation (transcription audio, conversion de documents) et couvrir d’autres frameworks que Next.js. Si vous avez besoin d’un processus particulier, ouvrez une issue⁠.