Skip to main content
skill CX Codex

comfyui-node-basics — Claude Code skill for ComfyUI nodes

comfyui-node-basics is a Claude Code skill for defining and registering ComfyUI custom nodes with the V3 API, including their schema and execution.

MIT ★ 321 updated 2026-10-17

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add jtydhr88/comfyui-custom-node-skills
/plugin install comfyui-custom-nodes@comfyui-custom-node-skills
Open on GitHub

What comfyui-node-basics does

This skill covers the V3 node class: inherit from io.ComfyNode, use define_schema() to declare the node ID, category, inputs, and outputs, then put the computation in execute(). Return results with io.NodeOutput. The method arguments must match the schema input IDs, and the returned values must match the output count.

For registration, the guide uses ComfyExtension and a module-level comfy_entrypoint(). It also outlines the V1 approach with NODE_CLASS_MAPPINGS and contrasts it with V3. V3 methods are class methods, so node instance state is not available.

The skill targets Claude Code and Codex. It explains the code structure; you still implement the schema, computation, and registration in your project.

What it helps with

  • define inputs and outputs for a ComfyUI custom node
  • match schema input IDs to execute() arguments
  • register a V3 node through ComfyExtension
  • compare the V1 class pattern with the V3 API

Example prompts for the agent

  • Create a ComfyUI custom node with the V3 API, taking an image and returning an image.
  • Check whether my node’s execute() arguments match the IDs in its schema.
  • Show how to register a node class with ComfyExtension and comfy_entrypoint().

How to install comfyui-node-basics

1Plugin marketplace

/plugin marketplace add jtydhr88/comfyui-custom-node-skills
/plugin install comfyui-custom-nodes@comfyui-custom-node-skills

This installs the whole comfyui-custom-nodes plugin with all its skills

2Skills CLI (Vercel)

npx skills add jtydhr88/comfyui-custom-node-skills --skill comfyui-node-basics -a claude-code

3Manually: put the files in place

~/.claude/skills/comfyui-node-basics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/comfyui-node-basics/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about comfyui-node-basics

How do I install comfyui-node-basics in Claude Code?

Add the marketplace with /plugin marketplace add jtydhr88/comfyui-custom-node-skills, then install the plugin with /plugin install comfyui-custom-nodes@comfyui-custom-node-skills.

What does comfyui-node-basics do?

It explains how to define a ComfyUI node’s schema and computation with the V3 API, then register the node. It also compares V3 with the older V1 structure.

How does ComfyUI V3 registration differ from V1?

V3 uses ComfyExtension and a module-level comfy_entrypoint(). V1 instead registers classes through NODE_CLASS_MAPPINGS.

Source text

SKILL.md · MIT
---
name: comfyui-node-basics
description: ComfyUI custom node fundamentals - V3 node structure, Schema, inputs/outputs, registration. Use when creating new ComfyUI custom nodes, defining node classes, or setting up a custom node project.
---

# ComfyUI Custom Node Basics (V3 API)

ComfyUI uses Python classes to define nodes. The **V3 API** is the current recommended approach. Nodes inherit from `io.ComfyNode` and define a schema + execute method.

## Quick Start

```python
from comfy_api.latest import ComfyExtension, io

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Custom Node",
            category="my_category",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("strength", default=1.0, min=0.0, max=1.0, step=0.01),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
            ],
        )

    @classmethod
    def execute(cls, image, strength):
        result = image * strength
        return io.NodeOutput(result)
```

## V3 Node Class Structure

Every V3 node requires:

1. **Inherit from `io.ComfyNode`**
2. **`define_schema(cls)`** - classmethod returning `io.Schema`
3. **`execute(cls, ...)`** - classmethod performing the computation

```python
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class ImageBrighten(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageBrighten",          # unique identifier
            display_name="Brighten Image",     # shown in UI
            category="image/adjust",           # menu path
            description="Adjusts image brightness",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("factor", default=1.2, min=0.0, max=3.0, step=0.1),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
            ],
        )

    @classmethod
    def execute(cls, image, factor):
        result = torch.clamp(image * factor, 0.0, 1.0)
        return io.NodeOutput(result)
```

## io.Schema Fields

```python
io.Schema(
    node_id="UniqueNodeID",            # required: unique string ID
    display_name="Display Name",        # optional: shown in UI menus
    category="category/subcategory",    # menu hierarchy (default "sd")
    description="Node description",     # optional: tooltip text
    inputs=[...],                       # list of Input objects
    outputs=[...],                      # list of Output objects
    hidden=[...],                       # list of Hidden enum values
    is_output_node=False,               # True for nodes with side effects (save, preview)
    is_experimental=False,              # marks as experimental
    is_deprecated=False,                # marks as deprecated
    is_dev_only=False,                  # hidden unless dev mode enabled
    is_api_node=False,                  # marks as API-only node
    is_input_list=False,                # receive full lists instead of individual items
    not_idempotent=False,               # no cache sharing between identical instances (see lifecycle)
    accept_all_inputs=False,            # accept arbitrary inputs via **kwargs
    enable_expand=False,                # allow node expansion (subgraphs)
    search_aliases=["alias1", "alias2"],# alternative search terms
    essentials_category="Basic",        # optional: Essentials tab category
    price_badge=None,                   # optional: PriceBadge for API nodes
    has_intermediate_output=False,      # True for nodes with interactive UI that produce intermediate outputs
    loop_boundary=None,                 # "start"/"end": core loop validation (v0.36+, experimental)
)
```

## V3 Node Registration

V3 nodes are registered via `ComfyExtension` and `comfy_entrypoint()`:

```python
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="my_nodes",
            inputs=[io.String.Input("text", multiline=True)],
            outputs=[io.String.Output()],
        )

    @classmethod
    def execute(cls, text):
        return io.NodeOutput(text.upper())


class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [MyNode]


async def comfy_entrypoint() -> MyExtension:
    return MyExtension()
```

The `comfy_entrypoint()` function must be defined at the module level (in the file directly imported by ComfyUI).

## V1 Node Structure (Legacy Reference)

V1 nodes use class attributes and `NODE_CLASS_MAPPINGS`:

```python
class MyNodeV1:
    CATEGORY = "my_category"
    FUNCTION = "execute"
    RETURN_TYPES = ("IMAGE",)
    RETURN_NAMES = ("image",)

    @classmethod
    def INPUT_TYPES(s):
        return {
            "required": {
                "image": ("IMAGE",),
                "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0}),
            }
        }

    def execute(self, image, strength):
        return (image * strength,)

NODE_CLASS_MAPPINGS = {"MyNodeV1": MyNodeV1}
NODE_DISPLAY_NAME_MAPPINGS = {"MyNodeV1": "My Node V1"}
```

## Key Differences: V3 vs V1

| Aspect | V3 | V1 |
|---|---|---|
| Base class | `io.ComfyNode` | Plain class |
| Execute method | `execute` classmethod (fixed name) | Instance method (custom name via `FUNCTION`) |
| Inputs | `io.Schema(inputs=[...])` | `INPUT_TYPES()` dict |
| Outputs | `io.Schema(outputs=[...])` | `RETURN_TYPES` tuple |
| Return value | `io.NodeOutput(...)` | Plain tuple |
| Registration | `ComfyExtension` + `comfy_entrypoint()` | `NODE_CLASS_MAPPINGS` dict |
| State | No instance state (classmethods) | Instance state allowed |
| Hidden inputs | `cls.hidden.prompt`, etc. | kwargs from `"hidden"` dict |

## Important Rules

- `node_id` must be globally unique across all nodes
- `execute()` parameters must match input IDs exactly
- All methods are `@classmethod` in V3 (no instance state)
- Return `io.NodeOutput(val1, val2, ...)` matching output count
- Category uses `/` separator for hierarchy: `"image/transform"`
- Prefix category with `_` to hide from menus: `"_for_testing"`

## See Also

- `comfyui-node-datatypes` - Data types (IMAGE, LATENT, MASK, etc.)
- `comfyui-node-inputs` - Input configuration details
- `comfyui-node-outputs` - Output types and UI outputs
- `comfyui-node-packaging` - Project structure and packaging
- `comfyui-node-lifecycle` - Execution lifecycle and caching

© Terry Jia · MIT · jtydhr88/comfyui-custom-node-skills

Similar skills

SKILL.md skills catalog →

From the same set10

The whole set →
comfyui-node-packaging comfyui-node-packaging — a skill for structuring and publishing ComfyUI custom node packages, covering project layout, __init__.py registration, requirements.txt and WEB_DIRECTORY. CX Codex +1 ★ 321repo stars comfyui-node-outputs comfyui-node-outputs is a Claude Code skill documenting ComfyUI V3 node return types, io.NodeOutput, UI previews, and image-saving utilities. CX Codex +1 ★ 321repo stars comfyui-node-lifecycle comfyui-node-lifecycle is a Claude Code skill that explains ComfyUI node execution order, input validation, and caching. It covers debugging graphs and building custom nodes. CX Codex +1 ★ 321repo stars comfyui-node-migration comfyui-node-migration moves legacy ComfyUI custom nodes onto the V3 API: a step-by-step checklist, property and input-type mapping tables, and a before/after example. CX Codex +1 ★ 321repo stars comfyui-node-inputs comfyui-node-inputs configures input widgets and connection slots for ComfyUI custom nodes. Helps when defining sliders, text areas, dropdowns, and editors. CX Codex +1 ★ 321repo stars comfyui-node-advanced comfyui-node-advanced is a Claude Code skill for designing ComfyUI nodes with flexible inputs and matched types. It addresses cases where a fixed connection schema is insufficient. CX Codex +1 ★ 321repo stars comfyui-node-datatypes comfyui-node-datatypes is a Claude Code skill that describes ComfyUI input and output types. It is enabled when working with tensor, model, audio, video, 3D, and widget formats. CX Codex +1 ★ 321repo stars comfyui-node-frontend comfyui-node-frontend guides frontend JavaScript extension development for ComfyUI custom nodes, covering lifecycle hooks, custom DOM widgets, and graph events. CX Codex +1 ★ 321repo stars

Project sponsors

Companies that keep this analytics open