Imported from ruwwww/comfyui-expert-skill (SKILL.md). Install upstream with npx skills add ruwwww/comfyui-expert-skill. Copyright stays with the author.

ComfyUI Core Node Development

This skill guides you through developing custom ComfyUI nodes that interact with ComfyUI's internal architecture. It covers everything from simple utility nodes to complex model patches, custom samplers, and research paper implementations.

Bootstrap: Environment Setup

Before writing any code or referencing any source, run this setup:

ln -sfn ~/ComfyUI/comfy/ /comfy

This creates a stable symlink so all source lookups use /comfy/ as root. Every file reference in this skill uses this path.

Why this matters: ComfyUI's internal API is not stable across versions. The source at /comfy/ is the only authoritative truth. Your training data about ComfyUI internals may be outdated. When in doubt, grep /comfy/ and read what you find.

Best Practices

These rules exist because real-world ComfyUI node development has specific failure modes that are hard to debug if you don't know about them upfront.

BP-01: Read before writing. Before implementing any node that touches a ComfyUI subsystem, grep /comfy/ for the relevant module and read it. ComfyUI's internals evolve frequently — patterns that worked three months ago may be wrong today. This is the single most important rule.

BP-02: Clone before patching. When using ModelPatcher, always call .clone() and patch the clone. The original ModelPatcher is shared across the graph — mutating it in place causes unpredictable cross-node interference. The clone() method is lightweight because it shares the underlying model weights.

BP-03: Respect dtype and device. Tensors in ComfyUI can be fp32, fp16, bf16, or quantized (GGUF, NF4, etc). Custom ops must be dtype-agnostic or explicitly cast with .to(dtype). Never assume tensors are on CPU — they may be on any CUDA device, and ComfyUI manages device placement through model_management.

BP-04: Preserve the LATENT contract. The LATENT type is always a dict with at least "samples" (a tensor). It may also contain "noise_mask", "batch_index", and other keys. Return it as a dict. Never return a raw tensor where a LATENT is expected, and preserve any keys you don't modify.

BP-05: Use model_options for sampler-time hooks. Don't monkey-patch model attributes at node execution time. Use model_options["transformer_options"] and the set_model_patch / set_model_patch_replace methods so patches are scoped to a single sampling call and don't leak state.

BP-06: Implement only the delta. When implementing a paper, identify the closest existing ComfyUI module, read its forward pass, identify exactly where the paper's contribution diverges, and implement only that divergence. Full reimplementations are fragile and miss ComfyUI-specific handling (dtype casting, device management, nested tensors, etc).

BP-07: Node outputs are lazy. Never perform heavy computation in INPUT_TYPES or __init__. All work happens in the execute method (the function named by FUNCTION). INPUT_TYPES is called frequently for UI rendering.

BP-08: Surface errors with meaning. Use raise ValueError("NodeName: <specific problem>") so users see which node failed and why. Raw tracebacks through ComfyUI's execution engine are hard to trace back to the source.

BP-09: Test with a minimal graph. For sampling/attention patches, test with a minimal KSampler graph before integrating into a complex workflow. This isolates whether your patch works from whether the workflow wiring is correct.

BP-10: Avoid name collisions. Check your NODE_CLASS_MAPPINGS keys against existing installed nodes. Name collisions silently override the previous node with no warning.

Domain Reference Files

This skill is organized by domain. Read the relevant reference file before implementing in that domain:

Paper-to-Code Workflow

When implementing a research paper into ComfyUI, follow this decision tree:

Step 1: Parse the contribution

Read the paper (or description) and classify what it changes:

• Attention mechanism → read references/pipelines/attention_patching.md
• Sampling/guidance → read references/pipelines/sampling_pipeline.md
• Model architecture → read references/core/model_architecture.md
• Conditioning/encoding → read references/core/conditioning.md
• Latent/VAE processing → read references/core/latent_ops.md

Is there a reference implementation? If yes, read it. If no, proceed to Step 2.

Step 2: Identify the insertion point

# Find the relevant operation in ComfyUI source
grep -rn "relevant_function_or_class" /comfy/

Read the actual forward pass to understand:

• What tensor shapes flow through
• What dtype/device assumptions exist
• What model_options / transformer_options keys are already used
• Where hook points exist

Step 3: Determine integration strategy

Step 4: Implement the delta

Write only what the paper changes, not a full reimplementation. Use existing ComfyUI infrastructure for everything else.

Step 5: Wire into the type system

Define INPUT_TYPES, RETURN_TYPES, RETURN_NAMES, FUNCTION, CATEGORY following the patterns in references/node_registration.md.

Step 6: Add cache invalidation

Add IS_CHANGED if the node has non-tensor state that affects outputs (e.g., random seeds, external file timestamps, configuration that doesn't flow through inputs).

File Structure

For any non-trivial implementation, organize the custom node package like this:

custom_nodes/
└── comfyui_<name>/
    ├── __init__.py           # NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
    ├── nodes.py              # Node class definitions
    ├── model_utils.py        # Model loading / patching helpers (if needed)
    ├── attention_patches.py  # Attention modification logic (if needed)
    ├── sampling.py           # Custom sampler logic (if needed)
    └── README.md             # What the nodes do, expected inputs/outputs

The __init__.py is the entry point — ComfyUI discovers nodes by importing this module and reading NODE_CLASS_MAPPINGS.

# __init__.py pattern
from .nodes import MyNode, MyOtherNode

NODE_CLASS_MAPPINGS = {
    "MyNode": MyNode,
    "MyOtherNode": MyOtherNode,
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "MyNode": "My Node (PackName)",
    "MyOtherNode": "My Other Node (PackName)",
}

__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

GitHub Reference Repositories

These repos demonstrate patterns at different complexity levels. Read the actual source when relevant — don't rely on cached knowledge of these repos, as they evolve alongside ComfyUI:

To fetch and study a reference repo:

# Clone to a temp location and read the relevant module
git clone --depth 1 https://github.com/<owner>/<repo>.git /tmp/<repo>
# Then grep/read the specific patterns you need

Quick Reference: Key Source Files

When you need to understand a subsystem, start with these files: