このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
difyctl skills install を実行して、お使いのマシンのコーディングエージェント向けにスキルファイルを書き込みます。エージェントはそれを読み取り、自身で接続を完了します。
インストールされる SKILL.md はブートストラップであり、マニュアルではありません。インストール済みの difyctl に対して 2 段階で検出を進めるようエージェントを導きます。
- エージェントは
difyctl help -o json --compactで コンパクトなコマンド一覧 を読み取り、リクエストに合うコマンドを 1 つ選びます。 - 実行前に、エージェントは
difyctl help <path> -o jsonでそのコマンドの ディスクリプタ を読み取ります。<path>は一覧に載っているコマンドそのもので、たとえばget appです。ディスクリプタは、そのコマンドの引数とフラグをエージェントが知る唯一の情報源です。
スキルはさらに、終了コード、エラー出力、ワークフローの一時停止、リトライのルールについては difyctl help agent を参照するようエージェントに指示します。ディスクリプタの effect ラベル（read、write、destructive）は確認のゲートも兼ねます。スキルの指示により、エージェントは write や destructive のコマンドを実行する前にあなたに確認を取ります。
スキルを使う場面#
- お使いのエージェントランタイムがスキルを読み取る場合：Claude Code、Codex、OpenCode、Cursor、pi、またはスキルディレクトリから
SKILL.mdファイルを読み取るその他のツール。 - エージェントが Shell コマンドを実行できる場合。スキルはエージェントの Shell ツールを介して
difyctlを駆動します。 - メンテナンス不要を望む場合：スキルはコマンドを一切列挙しないため、古くなることがありません。
ランタイムがスキルを読み取らない場合は、同じ 2 つのコマンドをエージェント自身の指示に書き込みます。追加する一文については、エージェントをオンボーディングする を参照してください。
前提条件#
- エージェントが動作するマシンで
difyctlを インストール し、サインイン して、セッションを再利用できるようにします。サーバーやコンテナの場合は、エージェントの動作環境で認証する を参照してください。 - スキルを読み取り、Shell コマンドを実行できるコーディングエージェントを使用します。Shell へのアクセスがないサンドボックス化されたエージェントはスキルを使用できません。
- インストール前にエージェントを少なくとも 1 回起動し、
difyctl skills installが見つけられるよう設定ディレクトリを作成しておきます。
手順#
スキルの書き込み先をプレビューする
--yes を付けない場合、このコマンドはドライランです。
スキルを書き込む
--yes は検出されたすべてのエージェントに書き込みます。--agent <name> を渡すと、1 つだけに書き込みます。
新しいエージェントセッションを開始する
新しいセッションを開始して、エージェントが受け取ったばかりのスキルをインデックス化できるようにします。
detection、エージェントごとのターゲットパス、--agent、--stdout、明示的なディレクトリ指定の形式については、スキルリファレンスページ を参照してください。
テスト#
インストール時に書き込んだパスが表示されます。そのファイルを開いて、スキルが存在することを確認してください。次に、エージェントが実際にそれを使用しているか確認します。
- 検出：新しいセッションで、エージェントに「
difyctlで何ができますか？」と尋ねます。正しく接続されたエージェントはdifyctl help -o json --compactを実行し、コマンドを推測するのではなく、その出力に基づいて回答します。 - エンドツーエンド：エージェントに Dify アプリを一覧表示させ、そのうちの 1 つを実行させます。
difyctl get app -o jsonの後に、一覧の実際の ID を使ったdescribe/runのシーケンスが続くか確認します。run appはwriteコマンドなので、実行前にエージェントが確認を求めてくるはずです。 - 一時停止の処理：人間の入力ステップを持つ Workflow または Chatflow のアプリがある場合、エージェントにそれを実行させます。一時停止した実行は 0 で終了し、stdout に
"status": "paused"を報告します。エージェントは一時停止を認識して再開を申し出るべきであり、失敗を報告したり実行を再試行したりするべきではありません。
トラブルシューティング#
| 問題 | 対処方法 |
|---|---|
| エージェントが検出されない | エージェントが少なくとも 1 回実行されるまで、その設定ディレクトリ（例：~/.claude）は存在しません。一度起動するか、difyctl skills install <dir> --yes でディレクトリを明示的に指定します。 |
| スキルはインストールされたが、エージェントが無視する | ほとんどのエージェントはセッション開始時にスキルをインデックス化するため、新しいセッションを開始します。それでも読み込まれない場合は、エージェントがスキルを読み取るディレクトリにインストーラーを向けます。 |
| コマンドが終了コード 4 で失敗する | エージェントに再利用できるセッションがありません。まずそのマシンでサインインしてください：エージェントの動作環境で認証する を参照してください。 |
| スキルが CLI より古い | スキルにはバージョンスタンプが付いており、エージェントに difyctl version との比較を指示します。異なる場合は、difyctl skills install --yes を再実行して上書きします。 |
その他の問題については、トラブルシューティング ページ全体を参照してください。