Transloadit のエージェントスキルを構築した方法
エージェントに MCP サーバーや CLI を与えると、Assemblyの作成、ファイルのアップロード、変換処理の実行ができます。しかし、2 つのセッションで「この動画を HLS にエンコードして」と依頼すると、呼び出しの順序もエラー処理も異なり、使用するTemplateや出力先についての前提も変わります。
Agent Skills は、こうした問題をすべて解決します。バージョン管理された Markdown の手順書で、何をどの順序で実行し、結果をどう検証するかを定めます。

Transloadit Agent Skills を公開しました。HLS エンコードから Uppy の統合まで、メディア処理ワークフローを網羅する
SKILL.md ファイルの小さなカタログです。公開後もカタログは進化していますが、ここで紹介する設計上の学びは今も有効です。
Agent Skills 標準
Anthropic は 2025年12月に Agent Skills を発表しました。スキルは、SKILL.md ファイルを含むディレクトリです。このファイルは YAML フロントマター(name、description)と、指示を記述した Markdown 本文で構成されます。エージェントはスキルを自動検出します。Claude Code は .claude/skills/、Codex は
.codex/skills/、Cursor は .cursor/skills/ を参照します。
この形式は意図的にシンプルにしています。スキルは新たなランタイムでもフレームワークでもありません。環境内にすでにあるツールで何をすべきかをエージェントに伝えます。スキルはリポジトリ内の通常のファイルなので、ほかのコードと同じようにレビューできます。
OpenAI は Codex 向けの openai/skills で、同じ SKILL.md 形式を採用しました。Microsoft は Azure と Copilot 向けに microsoft/skills を公開しました。Vercel は、35 を超えるエージェントプラットフォームにスキルをインストールする
npx skills CLI を構築しました。
構築したもの
公開時のカタログは、3 つのカテゴリを中心に構成しました。
リファレンス
docs-transloadit-robots– Robotのパラメーターと使用例をオフラインで参照できます。エージェントはこれを使い、推測に頼らずstepsJSON を作成、検証します。
変換(単発の処理、出力をローカルにダウンロード)
transform-encode-hls-video-with-transloadit– HLS エンコード。ローカルの動画を入力し、アダプティブストリーミング用のプレイリストを出力します。transform-generate-image-with-transloadit– AI 画像生成。プロンプトを入力し、画像ファイルを出力します。
統合(実際のアプリにひな形コードを追加)
integrate-uppy-transloadit-s3-uploading-to-nextjs– Next.js アプリに Uppy Dashboard と Transloadit によるアップロードを追加します。サーバー側での署名生成に対応し、必要に応じて S3 へのエクスポートも追加します。integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs– Next.js プロジェクトに Smart CDN の URL 署名を追加し、画像や動画を必要に応じて動的に配信します。
最上位の transloadit スキルがルーターとして機能します(詳細は後述します)。この公開時点の一覧がすべてではありません。現在のカタログは、リポジトリと検出用インデックスを参照してください。
ルーター
カタログ全体をエージェントのコンテキストに詰め込むのではなく、transloadit スキルがリクエストを読み取り、適切なスキルに振り分けます。
- リファレンスが必要(Robot のパラメーター、使用例、API 呼び出しなし)→
docs-transloadit-robots - 単発の変換が必要(出力をローカルにダウンロード)→
transform-* - エンドツーエンドのコード統合が必要 →
integrate-*
エージェントがルーターを自動的に読み込み、ルーターがサブスキルを読み込みます。各サブスキルの範囲を十分に絞ることで、エージェントはその場で手順を考えるのではなく、決まった経路に沿って進みます。
決定論的な CLI
エージェントに任せきりにすると、存在しないフラグを作り出したり、誤ったTemplateを選んだり、出力のダウンロードを忘れたりします。開発中に何度もこうした挙動を目にしました。そこで、各 transform-* スキルでは、特定のコマンドを 1 つ指定しています。
npx -y @transloadit/node assemblies create \
--template builtin/encode-hls-video@latest \
-i ./input.mp4 \
-o ./out/ \
-j
Builtin Template(builtin/encode-hls-video@latest)には私たちのベストプラクティスが組み込まれているため、エージェントがAssembly Instructionsを最初から作成する必要はありません。-o フラグは、結果を一時 URL に残すのではなく、ローカルディレクトリにダウンロードします。また、npx -y により、グローバルインストールとバージョンの不一致を避けます。
try-skill.ts によるテスト
読みやすくても、動かないコードを生成するスキルは、スキルがないよりも悪いものです。それを検出するために try-skill.ts を構築しました。各統合スキルをエンドツーエンドで検証します。
- クリーンなスタータープロジェクトを、隔離されたディレクトリにコピーします。
- 完全自律モードで動作するエージェント(OpenAI Codex)にスキルを注入します。
- エージェントにスキルを適用させ、ファイルの書き込みやコマンドの実行を行わせます。
- その結果に対して、プロジェクトのエンドツーエンドテストを実行します。
各スキルには受け入れ基準があります。たとえば Uppy 統合スキルでは、実際に Uppy Dashboard 経由で PNG をアップロードし、Transloadit の結果が返ることを確認する必要があります。モックは使いません。
テストが失敗したときは、記述を厳密にし、より明確なパスを追加して、再実行しました。試行錯誤の大半はここに費やしました。スキル自体は開発者ガイドのように読める内容で、テスト専用の指示は混在させていません。
スキルと MCP をいつ使い分けるか
エージェントが実行時に Transloadit のツールへ直接アクセスできる Transloadit MCP Server も公開しました。違いは明確です。MCP はエージェントに機能を提供します(Assemblyの作成、Templateの一覧取得、ファイルのアップロード)。一方、スキルはその機能を適切に使う方法を教えます(どのTemplateを選び、どのフラグを渡し、どこに出力を置くか)。
実際には、MCP は Transloadit を繰り返し実行する自律型パイプラインに適しています。スキルは、セットアップ、ひな形の生成、1 回限りのエンコードなど、人が指示する単発の作業に適しています。スキルからエージェントに、実行には MCP を呼び出すよう指示したり、MCP が利用できない場合は CLI に切り替えるよう指示したりすることもできます。
詳しい比較とセットアップ手順は、AI エージェントのドキュメントを参照してください。
インストール
npx skills add transloadit/skills
これで現在のカタログからスキルがインストールされます。また、スキルは
/.well-known/skills/index.json 経由でも、Agent Skills Discovery 仕様に従って自動検出できます。
npx skills add https://transloadit.com
手動でインストールする場合は、transloadit/skills リポジトリをクローンするか、シンボリックリンクを作成してください。
| エージェント | パス |
|---|---|
| Claude Code | .claude/skills/ |
| OpenAI Codex | .codex/skills/ |
| Gemini CLI | .gemini/skills/ |
| Cursor | .cursor/skills/ |
| Windsurf | .codeium/windsurf/skills/ |
クライアントの詳しい設定は、AI エージェントのドキュメントを参照してください。
今後の予定
変換スキル(音声文字起こし、ドキュメント変換)を増やし、Next.js 以外のフレームワークにも対応したいと考えています。必要なワークフローがあれば、issue を作成してください。
