So haben wir Transloadit Agent Skills entwickelt

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Stellen Sie einem Agenten einen MCP-Server oder eine CLI bereit, und er kann Assemblies erstellen, Dateien hochladen und Transformationen ausführen. Bitten Sie jedoch zwei Sitzungen, „dieses Video als HLS zu codieren“, erhalten Sie unterschiedliche Abfolgen von Aufrufen, eine unterschiedliche Fehlerbehandlung und unterschiedliche Annahmen dazu, welches Template verwendet und wo die Ausgaben abgelegt werden sollen.

Agent Skills⁠ lösen all diese Probleme. Es sind versionsverwaltete Markdown-Playbooks, die vorgeben, was in welcher Reihenfolge zu tun ist und wie das Ergebnis geprüft wird.

Wir haben Transloadit Agent Skills⁠ veröffentlicht: einen kleinen Katalog aus SKILL.md-Dateien für Workflows zur Medienverarbeitung, vom HLS-Encoding bis zur Uppy-Integration. Der Katalog wurde seit der Einführung weiterentwickelt, doch die hier erläuterten Design-Erkenntnisse gelten weiterhin.

Der Agent Skills-Standard

Anthropic führte Agent Skills⁠ im Dezember 2025 ein. Ein Skill ist ein Verzeichnis mit einer SKILL.md-Datei: YAML-Frontmatter (name, description) und ein Markdown-Text mit Anweisungen. Agenten erkennen Skills automatisch. Claude Code sucht in .claude/skills/, Codex in .codex/skills/ und Cursor in .cursor/skills/.

Das Format ist bewusst einfach gehalten. Ein Skill ist weder eine neue Runtime noch ein neues Framework. Er teilt einem Agenten mit, was mit den bereits in seiner Umgebung vorhandenen Tools zu tun ist. Da Skills einfache Dateien in Ihrem Repository sind, durchlaufen sie wie alle anderen Dateien ein Code-Review.

OpenAI übernahm dasselbe SKILL.md-Format 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-Nachschlagewerk für Robot-Parameter und -Beispiele. Agenten verwenden es, um steps-JSON ohne Spekulationen zu entwerfen oder zu validieren.

Transformationen (einmalige Verarbeitung, Ausgaben werden lokal heruntergeladen)

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

Integrationen (Code-Gerüst in eine echte Anwendung einfügen)

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

Ein übergeordneter transloadit-Skill dient als Router (mehr dazu weiter unten). Den aktuellen Katalog finden Sie im Repository und im Discovery-Index. Betrachten Sie diese Momentaufnahme zum Start nicht als vollständig.

Der Router

Statt den gesamten Katalog in den Kontext des Agenten zu laden, liest der transloadit-Skill die Anfrage und leitet sie an den passenden Skill weiter:

1. Referenz benötigt (Robot-Parameter, Beispiele, keine API-Aufrufe) → docs-transloadit-robots
2. Einmalige Transformation benötigt (Ausgaben lokal herunterladen) → transform-*
3. End-to-End-Code-Integration benötigt → integrate-*

Der Agent erkennt den Router automatisch, der Router wählt den untergeordneten Skill aus, und jeder untergeordnete Skill ist so eng abgegrenzt, dass der Agent einem einzigen Pfad folgt, statt zu improvisieren.

Deterministische CLI

Ohne klare Vorgaben erfindet ein Agent Flags, wählt das falsche Template oder vergisst, Ausgaben herunterzuladen. Das haben wir während der Entwicklung wiederholt beobachtet. Jeder transform-*-Skill 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 neu zusammenstellt. Das Flag -o lädt Ergebnisse in ein lokales Verzeichnis herunter, statt sie nur über eine temporäre URL bereitzustellen. 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. Deshalb haben wir try-skill.ts⁠ entwickelt. Das Tool validiert jeden Integrations-Skill End-to-End:

1. Ein unverändertes Starterprojekt in ein isoliertes Verzeichnis kopieren.
2. Den Skill in einen Agenten (OpenAI Codex) einspeisen, der im vollständig autonomen Modus ausgeführt wird.
3. Den Agenten den Skill anwenden lassen: Dateien schreiben und Befehle ausführen.
4. Die End-to-End-Tests des Projekts mit dem Ergebnis ausführen.

Für jeden Skill gelten Akzeptanzkriterien⁠. Der Uppy-Integrations-Skill muss beispielsweise tatsächlich eine PNG-Datei über das Uppy Dashboard hochladen und bestätigen, dass ein Transloadit-Ergebnis zurückgegeben wird. Keine Mocks.

Wenn Tests fehlschlugen, haben wir die Formulierungen präzisiert, explizitere Pfade ergänzt und die Tests erneut ausgeführt. Der größte Teil der Iterationszeit floss in diesen Bereich. Die Skills selbst lesen sich wie Entwicklerleitfäden; testspezifische Anweisungen gelangen nicht hinein.

Wann Skills und wann MCP sinnvoll sind

Wir haben außerdem einen Transloadit MCP Server veröffentlicht, der Agenten direkten Runtime-Zugriff auf Transloadit-Tools bietet. Der Unterschied ist eindeutig: MCP stellt Agenten Fähigkeiten bereit (Assemblies erstellen, Templates auflisten, Dateien hochladen), während Skills Agenten vermitteln, wie sie diese Fähigkeiten sinnvoll einsetzen (welches Template gewählt wird, welche Flags übergeben werden und wo Ausgaben abgelegt werden).

In der Praxis eignet sich MCP für autonome Pipelines, in denen Transloadit wiederholt ausgeführt wird. Skills eignen sich für von Menschen gesteuerte, einmalige Aufgaben wie Einrichtung, Scaffolding oder ein 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 die Einrichtungsanleitung finden Sie in der Dokumentation zu KI-Agenten.

Installation

npx skills add transloadit/skills

Damit werden alle sechs Skills installiert. Die Skills können außerdem automatisch über /.well-known/skills/index.json erkannt werden, entsprechend der Agent Skills Discovery-Spezifikation⁠:

npx skills add https://transloadit.com

Für die manuelle Installation klonen Sie das Repository transloadit/skills⁠ oder erstellen Sie einen Symlink darauf:

Eine ausführliche Client-Konfiguration finden Sie in der Dokumentation zu KI-Agenten.

Wie es weitergeht

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