comfyui-skill-public

name

comfyui-skill-public

description

Portable ComfyUI workflow and API guidance for any install. Use when building, validating, or troubleshooting ComfyUI image/video workflows, discovering available nodes/models via /object_info, wiring loaders/encoders/VAEs/LoRAs correctly, submitting jobs through the REST or WebSocket APIs, training LoRAs with ComfyUI, adapting a workflow to an unknown user machine without assuming specific checkpoints, paths, hardware, or custom nodes.

ComfyUI Portable Skill

Use this skill when the task is to work with ComfyUI in a reusable, installation-agnostic way.

Minimum trigger scope

Trigger on requests like:

• "Build a ComfyUI workflow"
• "Fix this ComfyUI workflow"
• "Use the ComfyUI API"
• "Why is this ComfyUI graph failing?"
• "Add a LoRA / model / node to this ComfyUI setup"
• "Train a LoRA on this dataset"
• "Run a batch on these images"
• "Generate a video with LTX"
• "Edit these photos with FLUX"
• "Run a video batch"
• "JoyCaption these images and generate prompts"

First move: assume zero install knowledge

Before writing or editing any workflow:

1. Read setup.md if the install is unknown.
2. Collect the missing setup fields from the user or discover them from the running ComfyUI instance via /object_info.
3. Prefer discovery over assumptions — confirm checkpoints, VAEs, encoders, and LoRAs from the target install.
4. Stop and report missing requirements clearly.

Read path by task

• Cold-start instructions for an AI agent -> AGENTS.md
• Setup / first run / portability questions -> setup.md
• Prompting guide index (all families) -> prompting-guides/README.md
• LTX 2.3 video or image-to-video generation -> prompting-guides/ltx-2.3-prompting-guide.md
• FLUX 2 image generation/edit prompting -> prompting-guides/flux-2-prompting-guide.md
• WAN 2.2 video prompting -> prompting-guides/wan-2.2-prompting-guide.md
• Batch jobs with state tracking, monitoring, and cron job setup -> batch-operations.md
• Batch cron jobs, notification templates, and error recovery SOP -> cron-jobs.md
• FLUX image edit / FLUX T2I / LTX / WAN / Hunyuan node maps and code patterns -> reference-implementations.md
• Production-ready ComfyUI API helper (persistent WS, reconnect, env config) -> scripts/api_lib.py
• Sanitized batch script starter -> scripts/template_run_batch.py
• JoyCaption-driven image-to-prompt pipeline convention -> docs/joycaption-convention.md
• Demo workflow JSON files (FLUX image edit, FLUX T2I, LTX video) -> demo-workflows/ — for demonstration only; replace with your own workflows
• External dependencies (JoyCaption, ComfyUI, Python packages) -> dependencies.md
• API submission / queue / history / WebSocket -> api.md
• Programmatic graph building, compatibility checks, and debugging -> workflow-patterns.md
• Model-family requirements and LoRA loading/training guidance -> models.md
• Prompt construction (general) -> prompting-guides/general-prompting-guide.md
• Release history -> changelog.md

Which guide to use (decision flow)

1. Is this first-time setup or unknown install? -> open setup.md first.
2. Is the requested model family known?
   • Yes -> open the family guide from prompting-guides/README.md.
   • No -> confirm via /object_info, then choose the family guide.
3. Is it a video task?
   • LTX family -> prompting-guides/ltx-2.3-prompting-guide.md
   • WAN family -> prompting-guides/wan-2.2-prompting-guide.md
4. Is it FLUX image generation/edit? -> prompting-guides/flux-2-prompting-guide.md
5. If still unclear, use prompting-guides/general-prompting-guide.md, then refine with the family guide.

Global operating rules

• Treat node classes as discoverable, not guaranteed constants.
• Treat model filenames as examples until confirmed on the target install.
• Use filename-only model references in workflow JSON unless the install explicitly requires a subdirectory path.
• Use defensive parsing for /history and /object_info; schema details can vary by ComfyUI version and custom nodes.
• Fail fast when a required node class, model, or custom node is missing.
• Keep setup-specific notes out of this file; put them in a per-user config or setup reference.
• Never edit a base workflow JSON file directly — always deep copy and patch.
• Demo workflow JSON files in demo-workflows/ are provided as working examples. Replace them with your own workflows adapted to your ComfyUI install.
• Never hardcode a ComfyUI host, input directory, Discord channel, model filename, or workflow path into a committed script. Use the scripts/api_lib.py env-var conventions (COMFYUI_HOST, COMFYUI_WS, COMFYUI_INPUT_DIR) or pass values through function arguments.
• Before generating prompts for an image set, check for an existing joycaption.md in the input folder (see docs/joycaption-convention.md). If found, ask the user: use it, update it, or start fresh.

Cold-read test

Before publishing or packaging changes, check that a fresh reader could answer:

• What does this skill do?
• When should it trigger?
• What must be discovered first?
• Where do install-specific values go?
• Which reference file should be opened for the current task?