Help us improve
Share bugs, ideas, or general feedback.
How this skill is triggered — by the user, by Claude, or both
Slash command
/comfy:comfyui-coreThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
ComfyUI workflows are JSON objects mapping **string node IDs** to node definitions:
Generates ComfyUI workflow JSON files from natural language descriptions for txt2img, img2img, txt2vid, img2vid, upscale, inpaint, audio, and 3D tasks. Outputs valid, importable JSON with model download links and custom node requirements.
Provides REST API gateway for ComfyUI servers with workflow management, job queuing via BullMQ, webhooks, caching, auth, rate limiting, and image delivery.
Troubleshoots ComfyUI errors like OOM, device mismatches, missing nodes, dtype issues, black images using diagnosis (get_history, get_logs) and fixes (FP8 models, lowvram, tiled VAE).
Share bugs, ideas, or general feedback.
ComfyUI workflows are JSON objects mapping string node IDs to node definitions:
{
"1": {
"class_type": "CheckpointLoaderSimple",
"inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" },
"_meta": { "title": "Load Checkpoint" }
},
"2": {
"class_type": "CLIPTextEncode",
"inputs": { "text": "a cat", "clip": ["1", 1] },
"_meta": { "title": "Positive Prompt" }
}
}
"1", "2", etc.)class_type is the exact Python class name of the nodeinputs contains both widget values (scalars) and connections (arrays)["sourceNodeId", outputIndex] — a 2-element array where:
output list (0-based)_meta is optional, used for display titles only"model": ["1", 0] // Connect to node 1's first output (MODEL)
"clip": ["1", 1] // Connect to node 1's second output (CLIP)
"vae": ["1", 2] // Connect to node 1's third output (VAE)
"positive": ["2", 0] // Connect to node 2's first output (CONDITIONING)
"samples": ["5", 0] // Connect to node 5's first output (LATENT)
"images": ["6", 0] // Connect to node 6's first output (IMAGE)
{ "1": { class_type, inputs }, "2": { ... } }{ "nodes": [...], "links": [...] } — includes layout positions, visual metadataget_workflow defaults to format="api" which auto-converts saved UI-format workflows to compact API format_meta.mode: "muted" — these are inactive but visible for understanding the workflow_meta.title and Constant key for tracing data flowanalyze_workflow(filename) — use this first to understand any saved workflow. Returns a structured text summary with sections, node IDs, key settings, virtual wires, and connection graph. No raw JSON — just what you need to reason about the workflow. Supports views: summary (default), overview (mermaid), detail (section mermaid), list, flat.list_workflows — list all saved workflows in ComfyUI's user libraryget_workflow(filename) — load raw workflow JSON. Only use when you need the actual JSON for enqueue_workflow, modify_workflow, or save_workflow. Use analyze_workflow instead for understanding.save_workflow(filename, workflow) — save a workflow to the user libraryComfyUI nodes pass typed data through connections:
| Type | Description | Common Source |
|---|---|---|
MODEL | Diffusion model weights | CheckpointLoaderSimple (output 0) |
CLIP | Text encoder | CheckpointLoaderSimple (output 1) |
VAE | Variational autoencoder | CheckpointLoaderSimple (output 2) |
CONDITIONING | Encoded text prompt | CLIPTextEncode (output 0) |
LATENT | Latent space tensor | EmptyLatentImage, KSampler, VAEEncode |
IMAGE | Pixel image tensor (BHWC) | VAEDecode, LoadImage, SaveImage |
MASK | Single-channel mask | LoadImage (output 1) |
UPSCALE_MODEL | Upscaling model | UpscaleModelLoader |
CheckpointLoaderSimple → MODEL, CLIP, VAE
├─ CLIP → CLIPTextEncode (positive) → CONDITIONING
├─ CLIP → CLIPTextEncode (negative) → CONDITIONING
│
EmptyLatentImage → LATENT
│
KSampler (model, positive, negative, latent_image) → LATENT
│
VAEDecode (samples, vae) → IMAGE
│
SaveImage (images)
Node IDs typically: 1=Checkpoint, 2=Positive, 3=Negative, 4=EmptyLatent, 5=KSampler, 6=VAEDecode, 7=SaveImage
Same as txt2img but replace EmptyLatentImage with:
LoadImage → IMAGE
VAEEncode (pixels, vae) → LATENT → KSampler.latent_image
Set KSampler.denoise to 0.5–0.8 (lower = closer to input image).
LoadImage → IMAGE
UpscaleModelLoader → UPSCALE_MODEL
ImageUpscaleWithModel (upscale_model, image) → IMAGE
SaveImage (images)
LoadImage (image) → IMAGE → VAEEncode → LATENT
LoadImage (mask) → MASK
SetLatentNoiseMask (samples, mask) → LATENT → KSampler.latent_image
create_workflow with template "txt2img" and your paramsenqueue_workflow with the returned JSON — returns prompt_id immediatelyget_job_status with the prompt_id until done is truelist_output_images (limit 1) to find the generated image, then Read to display itget_node_info — query what nodes are available and their schemasmodify_workflow — patch an existing workflow (set_input, add_node, remove_node, connect, insert_between)visualize_workflow — see a workflow as a mermaid diagramvisualize_workflow — workflow JSON → mermaid diagrammermaid_to_workflow — mermaid diagram → workflow JSON (uses /object_info for schema resolution)list_local_models — see what's installedsearch_models — find models on HuggingFacedownload_model — download to ComfyUI's models directoryImportant: Never ask the user to manually download models. If a required model is missing, proactively search for it and download it yourself:
list_local_models firstsearch_models or CivitAI via their REST APIdownload_model to install it directly to the correct subfolderCivitAI API (when CIVITAI_API_TOKEN env var is available):
GET https://civitai.com/api/v1/models?query={query}&types=Checkpoint&sort=Most+Downloaded&limit=5GET https://civitai.com/api/v1/models/{modelId}GET https://civitai.com/api/download/models/{modelVersionId}?token={token}CivitAI is preferred for fine-tuned models, community-rated checkpoints, and specialized LoRAs. HuggingFace is preferred for official/base models (SDXL, Flux, SD 1.5).
search_custom_nodes — search the ComfyUI Registryget_node_pack_details — get details about a specific packgenerate_node_skill — auto-generate a skill file for a node packenqueue_workflow submits to ComfyUI's queue and returns prompt_id + queue position immediately. It does NOT block.
After enqueuing one or more workflows, use a background Bash task to monitor progress silently:
# Single job
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <prompt_id>
# Multiple jobs (batch)
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <id1> <id2> <id3>
The script connects to ComfyUI's WebSocket and reports:
KSampler step 12/20 (60%))Standard generation pattern:
create_workflow or build workflow JSON + enqueue_workflow (repeat for batch)list_output_images or Read to display the generated imagesDo NOT poll get_job_status in a loop. The background monitor replaces polling entirely.
Fallback: If the monitor script is unavailable, use get_job_status to poll until done is true.
get_queue — shows running/pending job counts and prompt_idsget_job_status — check if a specific prompt_id is running, pending, or donecancel_job — interrupt a running job (pass optional prompt_id to target a specific one)cancel_queued_job — remove a specific pending job from the queue by prompt_idclear_queue — remove all pending jobs (does NOT stop the currently running job)When to use queue tools:
get_job_status for a quick boolean check (prefer background monitor for ongoing tracking)cancel_job stops what's running now; cancel_queued_job removes a pending oneclear_queue then optionally cancel_jobget_system_stats — GPU, VRAM, Python version, OS detailsget_queue — see running/pending jobs (also listed above under Queue Management)When ComfyUI is unresponsive or crashed:
get_system_stats — if it fails, ComfyUI is downrestart_comfyui to restart it (preserves launch args from prior stop_comfyui)start_comfyui or ask the user to start it manuallyWhen a job appears hung (monitor shows [STALL]):
get_system_stats — look at VRAM usage (OOM causes hangs)cancel_job to interrupt the stuck jobrestart_comfyui to force-restartclear_vram after restart to free GPU memory before retrying| Parameter | Type | Common Values |
|---|---|---|
seed | int | Random (0 to 2^48). Omit to auto-randomize. |
steps | int | 20 (standard), 4-8 (turbo/lightning models) |
cfg | float | 7-8 (SD 1.5/SDXL), 1.0 (Flux), 3.5 (turbo) |
sampler_name | string | "euler", "euler_ancestral", "dpmpp_2m", "dpmpp_sde" |
scheduler | string | "normal", "karras", "sgm_uniform" |
denoise | float | 1.0 (txt2img), 0.5-0.8 (img2img), 0.75-0.9 (inpaint) |
The visualize_workflow tool produces mermaid flowcharts with:
loading, conditioning, sampling, image, output-->|MODEL|, -->|CLIP|, -->|LATENT|, etc.LR (left-to-right) by default, TB (top-to-bottom) for large workflowsThe mermaid_to_workflow tool parses mermaid back into workflow JSON, using connection type labels to resolve the correct input/output slots via /object_info schemas.
["1", 0] not [1, 0] — node IDs are strings{ nodes: [], links: [] } — use API formatget_node_infoenqueue_workflow randomizes seeds by default unless disable_random_seed: true