ComfyUI Agent スキル

前提条件: CLIをインストールしてください: pip install -U comfyui-skill-cli。すべてのコマンドは、このプロジェクトのルートディレクトリ(この SKILL.md が存在する場所)から実行する必要があります。

[!IMPORTANT] ディレクトリ感度: CLIは現在のディレクトリから config.json と data/ を読み込みます。 コマンド実行前に、プロジェクトルートに 必ず cd してください。 症状: list が [] を返す、または server status が見つからないと報告する → 間違ったディレクトリにいます。

クイック判断

• ユーザーが「画像を生成する / 絵を描く」と言う → 実行フロー (ステップ1–4)
• ユーザーが「ワークフローをインポートする / ワークフローを追加する」と言う → comfyui-skill --json workflow import <path>
• ユーザーが「img2img / この画像を使う」と言う → まず comfyui-skill --json upload <image> を実行してから実行
• ユーザーが「inpainting / この領域をマスクする」と言う → comfyui-skill --json upload <mask> --mask を実行してから実行
• ユーザーが「以前の結果を表示する」と言う → comfyui-skill --json history list <id>
• ユーザーが「何が失敗したか / ジョブのステータスを確認する」と言う → comfyui-skill --json jobs list --status failed
• ユーザーが「どのサーバーがより多くのVRAMを持っているか」と言う → comfyui-skill --json server stats --all
• ユーザーが「どのノードが利用可能か」と言う → comfyui-skill --json nodes list
• ユーザーが「ドライラン / 実行せずにテストする」と言う → comfyui-skill --json run <id> --validate
• ユーザーが「管理UIを開く」と言う → python3 ./ui/open_ui.py

コア概念

• スキルID: <server_id>/<workflow_id>(例: local/txt2img)。サーバーが省略されている場合は、デフォルトサーバーが使用されます。
• スキーマ: 各ワークフローには schema.json があり、ビジネスパラメータ名(例: prompt、seed)を内部ComfyUIノードフィールドにマップします。ノードIDはユーザーに公開しないでください。
• サーバー: config.json で構成された1つ以上のComfyUIインスタンス。server status でヘルスチェックしてください。

コマンドリファレンス

コマンド	目的
comfyui-skill --json server status	ComfyUIサーバーがオンラインかどうかを確認
comfyui-skill --json server stats	VRAM、RAM、GPU、バージョンを表示(--all でマルチサーバー対応)
comfyui-skill --json list	利用可能なすべてのワークフローとパラメータをリスト表示
comfyui-skill --json info <id>	ワークフローの詳細とパラメータスキーマを表示
comfyui-skill --json submit <id> --args '{...}'	ワークフローを送信(ノンブロッキング)
comfyui-skill --json status <prompt_id>	実行ステータスを確認
comfyui-skill --json run <id> --args '{...}'	ワークフローを実行(ブロッキング、リアルタイムストリーミング)
comfyui-skill --json run <id> --validate	ワークフローを検証(実行しない)
comfyui-skill --json upload <path>	ComfyUIに画像をアップロード(img2imgワークフロー用)
comfyui-skill --json upload <path> --mask	マスク画像をアップロード(インペインティングワークフロー用)
comfyui-skill --json nodes list	利用可能なすべてのComfyUIノードをリスト表示
comfyui-skill --json jobs list	サーバー側のジョブ履歴をリスト表示(--status failed でフィルター)
comfyui-skill --json deps check <id>	足りない依存関係を確認
comfyui-skill --json deps install <id> --repos '[...]'	足りないカスタムノードをインストール
comfyui-skill --json workflow import <path>	ワークフローをインポート(自動検出、非推奨ノードについて警告)
comfyui-skill --json history list <id>	ワークフローの実行履歴をリスト表示

---

実行フロー

ステップ1: 利用可能なワークフローをクエリ

comfyui-skill --json list

すべての有効なワークフローとそのパラメータのJSON配列を返します。

• required: true のパラメータ → 提供されていない場合はユーザーに確認してください。
• required: false のパラメータ → コンテキストから推測(例: seed = ランダム番号)するか、省略します。
• ノードIDを公開しないでください。ビジネスパラメータ名(例: prompt、style)のみを使用してください。
• 複数のワークフローが一致する場合は、最も関連性の高いものを選ぶか、候補をリストアップしてください。

ステップ2: パラメータ組み立て

パラメータをJSON文字列に組み立てます。例:

{"prompt": "A beautiful landscape, high quality, masterpiece", "seed": 40128491}

重要なパラメータが足りない場合は、ユーザーに確認してください(例: 「どのようなビジュアルスタイルをお望みですか?」)。

ステップ3: プレフライト依存関係チェック

ワークフローの初回実行前に 必ず 実行してください:

comfyui-skill --json deps check <server_id>/<workflow_id>

• is_ready が true の場合 → ステップ4に進んでください。
• is_ready が false の場合:
  1. ユーザーに足りないノードとモデルを提示してください。
  2. ユーザーがインストールに同意した場合、以下を実行してください:

     comfyui-skill --json deps install <id> --repos '["https://github.com/repo1"]'
     

     チェックレポートの source_repo URLを --repos の値として使用してください。
  3. needs_restart が true の場合、ユーザーにComfyUIの再起動を伝えてから再度チェックしてください。
  4. 足りないモデルは手動でダウンロードする必要があります — ユーザーにどのフォルダに配置するかを伝えてください(例: checkpoints)。

ステップ4: ワークフローを実行

注: JSON引数はbashがダブルクォートを解析しないようにシングルクォートで囲む必要があります。

環境に応じて実行モードを選択してください:

インタラクティブモード: submit + status (チャット推奨)

ステップ4a — 送信:

comfyui-skill --json submit <id> --args '{"prompt": "..."}'

戻り値: {"status": "submitted", "prompt_id": "..."}. ユーザーに生成が開始されたことを伝えてください。

ステップ4b — ポーリング:

comfyui-skill --json status <prompt_id>

ステータス値: queued(with position) → running → success(with outputs) または error。

ポーリングパターン — リアルタイムフィードバックに重要:

各 status 呼び出しは 個別のツール呼び出し(個別のbashコマンド)である必要があります。シェルループを書かないでください。正しいパターンは:

1. status をスタンドアロンのbashコマンドとして実行してください。
2. 返されたJSONを読み取ってください。
3. queued または running の場合: ユーザーに進捗状況をテキストメッセージで送信してから、再度 status を実行してください。
4. success の場合: ステップ5に進んでください。
5. error の場合: エラーを報告してください。

ノンインタラクティブモード: ワンショットブロッキング(スクリプト/CI用)

comfyui-skill --json run <id> --args '{"prompt": "..."}'

完了するまでブロックします。status と同じ結果形式を success で返します。

ステップ5: 結果を提示

成功時、結果には outputs 配列が含まれ、ファイル参照(filename、subfolder、type)が含まれています。 ネイティブ機能を使用してファイルをユーザーに提示してください(例: 画像プレビュー、ファイルパス)。

---

ワークフローのインポート

ユーザーが新しいワークフローを追加したい場合(既存のものを実行するのではなく):

comfyui-skill --json workflow import <json_path>

• APIフォーマットとエディタフォーマットの両方をサポート(自動検出、自動変換)。
• スマートパラメータ抽出により自動的に schema.json を生成。
• インポート後、初回実行前に依存関係を確認してください。

ComfyUIサーバーまたはローカルフォルダからのバルクインポートについては、references/workflow-import.md を参照してください。

トラブルシューティング

1. ComfyUIオフライン: comfyui-skill --json server status を実行してください。オフラインの場合、ユーザーにComfyUIを起動するよう依頼してください。
2. ワークフローが見つからない: comfyui-skill --json list を実行して、利用可能なワークフローを確認してください。足りない場合、ユーザーはまずそれをインポートする必要があります。
3. パラメータフォーマットエラー: --args がシングルクォートで囲まれた有効なJSONであることを確認してください。
4. クラウドノード未認証: ワークフローがクラウドAPIノード(Kling、Soraなど)を使用しています。ユーザーに以下をガイドしてください: (1) https://platform.comfy.org でAPIキーを生成、(2) Web UI → サーバー設定 → 「ComfyUI APIキー」を入力。