Wie wir Transloadit Agent Skills entwickelt haben

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Geben Sie einem Agenten einen MCP-Server oder eine CLI, und er kann Assemblies erstellen, Dateien hochladen und Transformationen ausführen. Doch auf die Bitte „Codiere dieses Video in HLS“ liefern zwei Sitzungen unterschiedliche Abfolgen von Aufrufen, behandeln Fehler unterschiedlich und treffen unterschiedliche Annahmen darüber, welches Template sie verwenden und wo sie die Ergebnisse ablegen sollen.

Agent Skills⁠ lösen all diese Probleme. Sie sind versionierte Markdown-Anleitungen, die festlegen, was in welcher Reihenfolge zu tun ist und wie das Ergebnis überprüft wird.

Wir haben Transloadit Agent Skills⁠ veröffentlicht: einen kleinen Katalog von Dateien namens SKILL.md, die Medienworkflows vom HLS-Encoding bis zur Uppy-Integration abdecken. Der Katalog hat sich seit dem Start weiterentwickelt, doch die hier beschriebenen Erkenntnisse zum Design gelten weiterhin.

Der Standard Agent Skills

Anthropic stellte Agent Skills⁠ im Dezember 2025 vor. Ein Skill ist ein Verzeichnis mit einer Datei namens SKILL.md: Diese enthält YAML-Frontmatter (name, description) und einen Markdown-Hauptteil mit Anweisungen. Agenten entdecken Skills automatisch. Claude Code sucht in .claude/skills/, Codex in .codex/skills/, Cursor in .cursor/skills/.

Das Format ist bewusst einfach. Ein Skill ist keine neue Laufzeitumgebung und kein neues Framework. Er sagt einem Agenten, was er mit den bereits in seiner Umgebung verfügbaren Werkzeugen tun soll. Da Skills einfache Dateien in Ihrem Repository sind, durchlaufen sie wie alles andere Code-Reviews.

OpenAI übernahm dasselbe Format SKILL.md in openai/skills⁠ für Codex. Microsoft veröffentlichte microsoft/skills⁠ für Azure und Copilot. Vercel entwickelte die CLI npx skills⁠, um Skills auf mehr als 35 Agentenplattformen zu installieren.

Was wir entwickelt haben

Zum Start konzentrierte sich der Katalog auf drei Kategorien:

Referenz

• docs-transloadit-robots – Offline-Zugriff auf Robot-Parameter und Robot-Beispiele. Agenten nutzen dies, um JSON für steps ohne Raten zu entwerfen oder zu validieren.

Transformationen (einmalige Verarbeitung, Ergebnisse werden lokal heruntergeladen)

• transform-encode-hls-video-with-transloadit – HLS-Encoding. Ein lokales Video als Eingabe, eine Playlist für adaptives Streaming als Ausgabe.
• transform-generate-image-with-transloadit – KI-Bilderzeugung. Ein Prompt als Eingabe, eine Bilddatei als Ausgabe.

Integrationen (Codegerüst für eine echte App erstellen)

• integrate-uppy-transloadit-s3-uploading-to-nextjs – Uppy Dashboard und Transloadit-Uploads zu einer Next.js-App hinzufügen, mit serverseitiger Signaturerzeugung und optionalem S3-Export.
• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs – Smart-CDN-URL-Signierung zu einem Next.js-Projekt hinzufügen, um Bilder und Videos dynamisch auszuliefern.

Ein übergeordneter Skill namens transloadit dient als Router (mehr dazu unten). Den aktuellen Katalog finden Sie im Repository und im Discovery-Index. Diese Momentaufnahme zum Start ist keine vollständige Übersicht des heutigen Katalogs.

Der Router

Der Skill transloadit liest die Anfrage und wählt den passenden Skill aus, statt den gesamten Katalog in den Kontext des Agenten zu laden:

1. Referenz benötigt (Robot-Parameter, Beispiele, keine API-Aufrufe) → docs-transloadit-robots
2. Einmalige Transformation benötigt (Ergebnisse lokal herunterladen) → transform-*
3. Durchgängige Codeintegration benötigt → integrate-*

Der Agent findet den Router automatisch, der Router findet den passenden untergeordneten Skill, und jeder dieser Skills ist so eng gefasst, dass der Agent einem Ablauf folgt, statt zu improvisieren.

Deterministische CLI

Auf sich allein gestellt erfindet ein Agent Flags, wählt das falsche Template oder vergisst, Ergebnisse herunterzuladen. Das haben wir während der Entwicklung wiederholt beobachtet. Jeder Skill der Gruppe transform-* schreibt einen bestimmten Befehl vor:

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

Die Builtin Templates (builtin/encode-hls-video@latest) bilden unsere bewährten Verfahren ab, sodass der Agent Assembly Instructions nicht von Grund auf zusammenstellt. Das Flag -o lädt Ergebnisse in ein lokales Verzeichnis herunter, statt sie nur über eine temporäre URL zugänglich zu lassen. Und npx -y vermeidet globale Installationen und Versionskonflikte.

Tests mit try-skill.ts

Ein Skill, der sich gut liest, aber fehlerhaften Code erzeugt, ist schlechter als gar kein Skill. Um das zu erkennen, haben wir try-skill.ts⁠ entwickelt. Es validiert jeden Integrations-Skill von Anfang bis Ende:

1. Ein sauberes Starterprojekt in ein isoliertes Verzeichnis kopieren.
2. Den Skill in einen Agenten (OpenAI Codex) einbinden, der im vollständig autonomen Modus läuft.
3. Den Agenten den Skill anwenden lassen: Dateien schreiben und Befehle ausführen.
4. Die End-to-End-Tests des Projekts für das Ergebnis ausführen.

Jeder Skill hat Akzeptanzkriterien⁠. Der Skill für die Uppy-Integration muss zum Beispiel tatsächlich eine PNG-Datei über das Uppy Dashboard hochladen und bestätigen, dass ein Transloadit-Ergebnis zurückkommt. Dabei kommen keine Mocks zum Einsatz.

Wenn Tests fehlschlugen, präzisierten wir die Formulierungen, ergänzten explizitere Pfade und wiederholten die Tests. Hier floss der größte Teil der Zeit für die Überarbeitung ein. Die Skills selbst lesen sich wie Entwickleranleitungen; sie enthalten keine testspezifischen Anweisungen.

Wann Sie Skills oder MCP verwenden sollten

Wir haben auch einen Transloadit MCP Server veröffentlicht, der Agenten zur Laufzeit direkten Zugriff auf Transloadit-Werkzeuge gibt. Der Unterschied ist einfach: MCP gibt Agenten Fähigkeiten (Assemblies erstellen, Templates auflisten, Dateien hochladen). Skills zeigen Agenten, wie sie diese Fähigkeiten sinnvoll nutzen (welches Template sie wählen, welche Flags sie übergeben und wo sie Ergebnisse ablegen sollen).

In der Praxis eignet sich MCP für autonome Pipelines, in denen Transloadit wiederholt ausgeführt wird. Skills eignen sich für einmalige Aufgaben unter menschlicher Anleitung, etwa Einrichtung, Codegerüste oder einmaliges Encoding. Ein Skill kann den Agenten auch anweisen, MCP zur Ausführung aufzurufen oder auf die CLI zurückzugreifen, wenn MCP nicht verfügbar ist.

Den vollständigen Vergleich und Anleitungen zur Einrichtung finden Sie in der Dokumentation für KI-Agenten.

Installation

npx skills add transloadit/skills

Damit werden Skills aus dem aktuellen Katalog installiert. Die Skills lassen sich auch automatisch über /.well-known/skills/index.json entdecken, gemäß der Spezifikation Agent Skills Discovery⁠:

npx skills add https://transloadit.com

Für die manuelle Installation klonen Sie das Repository transloadit/skills⁠ oder legen einen symbolischen Link darauf an:

Details zur Client-Konfiguration finden Sie in der Dokumentation für KI-Agenten.

Wie es weitergeht

Wir möchten weitere Transformations-Skills hinzufügen (Audiotranskription, Dokumentenkonvertierung) und auch Frameworks jenseits von Next.js abdecken. Wenn Sie einen bestimmten Workflow benötigen, erstellen Sie ein Issue⁠.