К основному содержанию
скилл CX Codex

comfyui-node-migration — скилл для Claude Code: ноды ComfyUI V1→V3

Скилл comfyui-node-migration переводит старые кастомные ноды ComfyUI с API V1 на V3: чек-лист по шагам, таблицы соответствия свойств и типов входов, пример до и после.

MIT ★ 321 обновлён 2026-10-17

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add jtydhr88/comfyui-custom-node-skills
/plugin install comfyui-custom-nodes@comfyui-custom-node-skills
Открыть на GitHub

Что делает comfyui-node-migration

Скилл ведёт перенос кастомной ноды ComfyUI со старого API на V3. Внутри чек-лист: базовый класс меняется на io.ComfyNode, INPUT_TYPES() уступает место define_schema() с io.Schema, функция выполнения получает имя execute и декоратор @classmethod, а кортеж в возврате заменяется на io.NodeOutput.

Дальше по списку: IS_CHANGED становится fingerprint_inputs, VALIDATE_INPUTS — validate_inputs, check_lazy_status тоже делается classmethod. Регистрация переезжает с NODE_CLASS_MAPPINGS на ComfyExtension и comfy_entrypoint(), скрытые входы берутся из cls.hidden.

Для сверки даны таблицы: свойство V1 и его эквивалент в io.Schema, тип входа и его форма io.*.Input вплоть до Combo, ClipVision и File3DGLB. Пример ImageInvert показан дважды, до и после. В V3 у ноды нет состояния экземпляра, поэтому __init__ придётся убрать: код, который держал что-то в self, после миграции не заработает без переделки.

Какие задачи решает

  • переписать INPUT_TYPES() на define_schema() со схемой io.Schema
  • заменить NODE_CLASS_MAPPINGS на ComfyExtension с comfy_entrypoint()
  • найти новый вид для старого типа входа из таблицы io.*.Input
  • убрать __init__ и перенести состояние в cls.hidden
  • сверить возвращаемый кортеж с io.NodeOutput

Примеры запросов агенту

  • Переведи ноду ImageInvert с API V1 на V3 в ComfyUI
  • Покажи, как IS_CHANGED заменяется на fingerprint_inputs в моей ноде
  • Сконвертируй вход со списком опций в io.Combo.Input

Как установить comfyui-node-migration

1Через маркетплейс плагинов

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

Команда ставит плагин comfyui-custom-nodes целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/comfyui-node-migration/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о comfyui-node-migration

Как установить comfyui-node-migration в Claude Code?

Через маркетплейс плагинов: сначала /plugin marketplace add jtydhr88/comfyui-custom-node-skills, затем /plugin install comfyui-custom-nodes@comfyui-custom-node-skills.

Что делает comfyui-node-migration?

Проводит кастомную ноду ComfyUI через переход с V1 на V3: базовый класс, схема входов и выходов, регистрация расширения и скрытые входы.

Как в V3 читать скрытые входы вроде unique_id?

Через cls.hidden: в примере строка node_id = cls.hidden.unique_id стоит внутри execute, а в схеме скрытый вход объявлен как hidden=[io.Hidden.unique_id].

Исходный текст

SKILL.md · MIT
---
name: comfyui-node-migration
description: ComfyUI V1 to V3 node migration - converting legacy nodes to the V3 API. Use when migrating existing custom nodes from V1 to V3, understanding differences between API versions, or modernizing node code.
---

# ComfyUI V1 → V3 Migration Guide

Migrate existing V1 nodes to the modern V3 API. V3 uses classmethods, typed inputs/outputs, and `ComfyExtension` registration.

## Migration Checklist

1. Change base class to `io.ComfyNode`
2. Replace `INPUT_TYPES()` with `define_schema()` returning `io.Schema`
3. Rename execution function to `execute` and make it a `@classmethod`
4. Replace return tuples with `io.NodeOutput(...)`
5. Replace `IS_CHANGED` with `fingerprint_inputs`
6. Replace `VALIDATE_INPUTS` with `validate_inputs`
7. Convert `check_lazy_status` to `@classmethod`
8. Replace `NODE_CLASS_MAPPINGS` with `ComfyExtension` + `comfy_entrypoint()`
9. Access hidden inputs via `cls.hidden` instead of kwargs
10. Remove `__init__` methods (no instance state in V3)

## Side-by-Side Comparison

### V1 (Before)

```python
import torch

class ImageInvertV1:
    CATEGORY = "image"
    FUNCTION = "invert"
    RETURN_TYPES = ("IMAGE",)
    RETURN_NAMES = ("image",)
    OUTPUT_TOOLTIPS = ("The inverted image",)
    DESCRIPTION = "Inverts image colors"

    @classmethod
    def INPUT_TYPES(s):
        return {
            "required": {
                "image": ("IMAGE",),
                "strength": ("FLOAT", {
                    "default": 1.0,
                    "min": 0.0,
                    "max": 1.0,
                    "step": 0.01,
                }),
            },
            "optional": {
                "mask": ("MASK",),
            },
            "hidden": {
                "unique_id": "UNIQUE_ID",
            },
        }

    @classmethod
    def IS_CHANGED(s, image, strength, mask=None, unique_id=None):
        return strength

    @classmethod
    def VALIDATE_INPUTS(s, image, strength, mask=None, unique_id=None):
        if strength < 0:
            return "Strength must be non-negative"
        return True

    def invert(self, image, strength, mask=None, unique_id=None):
        inverted = 1.0 - image
        result = image * (1 - strength) + inverted * strength
        if mask is not None:
            result = image * (1 - mask.unsqueeze(-1)) + result * mask.unsqueeze(-1)
        return (result,)

NODE_CLASS_MAPPINGS = {"ImageInvertV1": ImageInvertV1}
NODE_DISPLAY_NAME_MAPPINGS = {"ImageInvertV1": "Invert Image"}
```

### V3 (After)

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

class ImageInvertV3(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageInvertV3",
            display_name="Invert Image",
            description="Inverts image colors",
            category="image",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("strength", default=1.0, min=0.0, max=1.0, step=0.01),
                io.Mask.Input("mask", optional=True),
            ],
            outputs=[
                io.Image.Output("IMAGE", tooltip="The inverted image"),
            ],
            hidden=[io.Hidden.unique_id],
        )

    @classmethod
    def fingerprint_inputs(cls, image, strength, mask=None):
        return strength

    @classmethod
    def validate_inputs(cls, image, strength, mask=None):
        if strength < 0:
            return "Strength must be non-negative"
        return True

    @classmethod
    def execute(cls, image, strength, mask=None):
        node_id = cls.hidden.unique_id  # access hidden via cls.hidden

        inverted = 1.0 - image
        result = image * (1 - strength) + inverted * strength
        if mask is not None:
            result = image * (1 - mask.unsqueeze(-1)) + result * mask.unsqueeze(-1)
        return io.NodeOutput(result)


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

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

## Property Mapping

| V1 Property | V3 Equivalent |
|---|---|
| `CATEGORY = "image"` | `io.Schema(category="image")` |
| `FUNCTION = "my_func"` | Always `execute` (fixed name) |
| `RETURN_TYPES = ("IMAGE",)` | `outputs=[io.Image.Output()]` |
| `RETURN_NAMES = ("image",)` | `outputs=[io.Image.Output(display_name="image")]` |
| `OUTPUT_TOOLTIPS = ("tip",)` | `outputs=[io.Image.Output(tooltip="tip")]` |
| `OUTPUT_NODE = True` | `io.Schema(is_output_node=True)` |
| `DEPRECATED = True` | `io.Schema(is_deprecated=True)` |
| `EXPERIMENTAL = True` | `io.Schema(is_experimental=True)` |
| `API_NODE = True` | `io.Schema(is_api_node=True)` |
| `NOT_IDEMPOTENT = True` | `io.Schema(not_idempotent=True)` |
| `DESCRIPTION = "..."` | `io.Schema(description="...")` |
| `SEARCH_ALIASES = [...]` | `io.Schema(search_aliases=[...])` |
| `INPUT_IS_LIST = True` | `io.Schema(is_input_list=True)` |
| `OUTPUT_IS_LIST = (True,)` | `io.Image.Output(is_output_list=True)` |
| `DEV_ONLY = True` | `io.Schema(is_dev_only=True)` |
| `ESSENTIALS_CATEGORY = "Basic"` | `io.Schema(essentials_category="Basic")` |

## Input Type Mapping

| V1 Input | V3 Input |
|---|---|
| `("IMAGE",)` | `io.Image.Input("id")` |
| `("MASK",)` | `io.Mask.Input("id")` |
| `("LATENT",)` | `io.Latent.Input("id")` |
| `("MODEL",)` | `io.Model.Input("id")` |
| `("CLIP",)` | `io.Clip.Input("id")` |
| `("VAE",)` | `io.Vae.Input("id")` |
| `("CONDITIONING",)` | `io.Conditioning.Input("id")` |
| `("INT", {"default": 0, ...})` | `io.Int.Input("id", default=0, ...)` |
| `("FLOAT", {"default": 1.0, ...})` | `io.Float.Input("id", default=1.0, ...)` |
| `("STRING", {"multiline": True})` | `io.String.Input("id", multiline=True)` |
| `("BOOLEAN", {"default": True})` | `io.Boolean.Input("id", default=True)` |
| `(["opt1", "opt2"],)` | `io.Combo.Input("id", options=["opt1", "opt2"])` |
| `("CONTROL_NET",)` | `io.ControlNet.Input("id")` |
| `("CLIP_VISION",)` | `io.ClipVision.Input("id")` |
| `("CLIP_VISION_OUTPUT",)` | `io.ClipVisionOutput.Input("id")` |
| `("STYLE_MODEL",)` | `io.StyleModel.Input("id")` |
| `("GLIGEN",)` | `io.Gligen.Input("id")` |
| `("UPSCALE_MODEL",)` | `io.UpscaleModel.Input("id")` |
| `("AUDIO",)` | `io.Audio.Input("id")` |
| `("VIDEO",)` | `io.Video.Input("id")` |
| `("SAMPLER",)` | `io.Sampler.Input("id")` |
| `("SIGMAS",)` | `io.Sigmas.Input("id")` |
| `("NOISE",)` | `io.Noise.Input("id")` |
| `("GUIDER",)` | `io.Guider.Input("id")` |
| `("HOOKS",)` | `io.Hooks.Input("id")` |
| `("LORA_MODEL",)` | `io.LoraModel.Input("id")` |
| `("MESH",)` | `io.Mesh.Input("id")` |
| `("VOXEL",)` | `io.Voxel.Input("id")` |
| `("FILE_3D",)` | `io.File3DAny.Input("id")` |
| `("FILE_3D_GLB",)` | `io.File3DGLB.Input("id")` |
| `("SVG",)` | `io.SVG.Input("id")` |
| `("COLOR",)` | `io.Color.Input("id")` |
| `("BOUNDING_BOX",)` | `io.BoundingBox.Input("id")` |
| `("CURVE",)` | `io.Curve.Input("id")` |
| `("LATENT_UPSCALE_MODEL",)` | `io.LatentUpscaleModel.Input("id")` |
| `("MODEL_PATCH",)` | `io.ModelPatch.Input("id")` |
| `("HOOK_KEYFRAMES",)` | `io.HookKeyframes.Input("id")` |
| `("AUDIO_ENCODER",)` | `io.AudioEncoder.Input("id")` |
| `("AUDIO_ENCODER_OUTPUT",)` | `io.AudioEncoderOutput.Input("id")` |
| `("TRACKS",)` | `io.Tracks.Input("id")` |
| `("LOSS_MAP",)` | `io.LossMap.Input("id")` |
| `("TIMESTEPS_RANGE",)` | `io.TimestepsRange.Input("id")` |
| `("LATENT_OPERATION",)` | `io.LatentOperation.Input("id")` |
| `("WEBCAM",)` | `io.Webcam.Input("id")` |
| `("PHOTOMAKER",)` | `io.Photomaker.Input("id")` |
| `("WAN_CAMERA_EMBEDDING",)` | `io.WanCameraEmbedding.Input("id")` |
| `("LOAD_3D",)` | `io.Load3D.Input("id")` |
| `("LOAD_3D_ANIMATION",)` | `io.Load3DAnimation.Input("id")` |
| `("LOAD3D_CAMERA",)` | `io.Load3DCamera.Input("id")` |
| `("FILE_3D_GLTF",)` | `io.File3DGLTF.Input("id")` |
| `("FILE_3D_FBX",)` | `io.File3DFBX.Input("id")` |
| `("FILE_3D_OBJ",)` | `io.File3DOBJ.Input("id")` |
| `("FILE_3D_STL",)` | `io.File3DSTL.Input("id")` |
| `("FILE_3D_USDZ",)` | `io.File3DUSDZ.Input("id")` |
| `("FILE_3D_PLY",)` | `io.File3DPLY.Input("id")` |
| `("FILE_3D_SPLAT",)` | `io.File3DSPLAT.Input("id")` |
| `("FILE_3D_SPZ",)` | `io.File3DSPZ.Input("id")` |
| `("FILE_3D_KSPLAT",)` | `io.File3DKSPLAT.Input("id")` |
| `("FILE_3D_SPLAT_ANY",)` | `io.File3DSplatAny.Input("id")` |
| `("FILE_3D_POINT_CLOUD_ANY",)` | `io.File3DPointCloudAny.Input("id")` |
| `("SPLAT",)` | `io.Splat.Input("id")` |
| `("LOAD3D_MODEL_INFO",)` | `io.Load3DModelInfo.Input("id")` |
| `("BACKGROUND_REMOVAL",)` | `io.BackgroundRemoval.Input("id")` |
| `("DICT",)` | `io.Dict.Input("id")` |
| `("ARRAY",)` | `io.Array.Input("id")` |
| `("COLORS",)` | `io.Colors.Input("id")` |
| `("BOUNDING_BOXES",)` | `io.BoundingBoxes.Input("id")` |
| `("RANGE",)` | `io.Range.Input("id")` |
| `("HISTOGRAM",)` | `io.Histogram.Input("id")` |
| `("POINT",)` | `io.Point.Input("id")` |
| `("FACE_ANALYSIS",)` | `io.FaceAnalysis.Input("id")` |
| `("BBOX",)` | `io.BBOX.Input("id")` |
| `("SEGS",)` | `io.SEGS.Input("id")` |
| `("IMAGECOMPARE",)` | `io.ImageCompare.Input("id")` |
| `("LAYERS",)` | `io.Layers.Input("id")` |
| `("COMPOSITOR",)` | `io.Compositor.Input("id")` |
| `("CAMERA_INFO_STATE",)` | `io.CameraInfoState.Input("id")` |
| `("VIDEO_EDIT",)` | `io.VideoEdit.Input("id", features=["trim", "crop"])` |
| `("RESOLUTION_PREVIEW",)` | `io.ResolutionPreview.Input("id")` |
| `("*",)` | `io.AnyType.Input("id")` or `io.MultiType.Input("id", types=[...])` |

## Method Migration

### Execute Method

```python
# V1: instance method with custom name
class V1Node:
    FUNCTION = "process"
    def process(self, image, value):
        return (result,)

# V3: classmethod named "execute", returns NodeOutput
class V3Node(io.ComfyNode):
    @classmethod
    def execute(cls, image, value):
        return io.NodeOutput(result)
```

### IS_CHANGED → fingerprint_inputs

```python
# V1
@classmethod
def IS_CHANGED(s, **kwargs):
    return float("NaN")  # always re-execute

# V3
@classmethod
def fingerprint_inputs(cls, **kwargs):
    import time
    return time.time()  # always re-execute
```

### VALIDATE_INPUTS → validate_inputs

```python
# V1
@classmethod
def VALIDATE_INPUTS(s, input_types=None, **kwargs):
    return True

# V3
@classmethod
def validate_inputs(cls, input_types=None, **kwargs):
    return True
```

### check_lazy_status

```python
# V1: instance method
def check_lazy_status(self, **kwargs):
    return ["input_name"]

# V3: classmethod
@classmethod
def check_lazy_status(cls, **kwargs):
    return ["input_name"]
```

### Hidden Inputs

```python
# V1: received as kwargs
def execute(self, image, unique_id=None, prompt=None):
    node_id = unique_id

# V3: accessed via cls.hidden
@classmethod
def execute(cls, image):
    node_id = cls.hidden.unique_id
    prompt = cls.hidden.prompt
```

## Registration Migration

```python
# V1
NODE_CLASS_MAPPINGS = {
    "Node1": Node1Class,
    "Node2": Node2Class,
}
NODE_DISPLAY_NAME_MAPPINGS = {
    "Node1": "Node One",
    "Node2": "Node Two",
}
WEB_DIRECTORY = "./js"

# V3
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

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

    @override
    async def on_load(self):
        # Optional: initialization logic
        pass

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

# WEB_DIRECTORY still works the same way for JS extensions
WEB_DIRECTORY = "./js"
```

## Output Node Migration

```python
# V1
class V1SaveNode:
    RETURN_TYPES = ()
    OUTPUT_NODE = True
    FUNCTION = "save"

    def save(self, images, prefix):
        # ... save logic ...
        return {"ui": {"images": results}}

# V3
from comfy_api.latest import io, ui

class V3SaveNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="V3SaveNode",
            display_name="Save",
            category="image",
            is_output_node=True,
            inputs=[
                io.Image.Input("images"),
                io.String.Input("prefix", default="output"),
            ],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, images, prefix):
        saved = ui.ImageSaveHelper.get_save_images_ui(images, prefix, cls=cls)
        return io.NodeOutput(ui=saved)
```

## Key Gotchas

1. **No instance state**: V3 execute is a classmethod. Don't store state on `self`. Use external storage if needed.
2. **Fixed method name**: Always `execute`, never custom names.
3. **Hidden access changed**: Use `cls.hidden.prompt` not function parameters.
4. **Return type changed**: `io.NodeOutput(val)` not `(val,)`.
5. **Optional inputs**: Use `=None` default in execute params, not separate `"optional"` dict.
6. **Async support**: V3 execute can be `async def execute(cls, ...)`.

## See Also

- `comfyui-node-basics` - V3 node fundamentals
- `comfyui-node-packaging` - Project structure
- `comfyui-node-lifecycle` - Execution lifecycle differences

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

Похожие скиллы

Все скиллы по теме «ИИ и ML» →
cli-anything-comfyui HKUDS Скилл cli-anything-comfyui даёт агенту консольный доступ к ComfyUI: ставить workflow в очередь, искать модели и скачивать готовые картинки без графического интерфейса. CX Codex +1 615установок comfyui NousResearch Подключает ComfyUI через REST/WebSocket API и comfy-cli. Запускает диффузионные пайплайны — от txt2img на Flux и SDXL до видео через AnimateDiff и Wan. CX Codex +1 405установок comfyui-lowvram-setup 0xheycat Скилл comfyui-lowvram-setup для Claude Code задаёт низкопамятную конфигурацию ComfyUI для генерации изометрических ассетов SDXL. Настраивает RTX 3060 с 12 ГБ видеопамяти и подготовку набора тайлов. CX Codex +1 ★ 51звёзд репо comfyui-mcp artokun MCP-сервер, который даёт агенту доступ к вашему ComfyUI: генерация картинок, видео и звука, правка графа и работа с моделями. CX Codex +1 ★ 946звёзд репо comfyui-mcp-server MetaBrain-Labs Подключает ComfyUI и превращает workflow в вызываемые инструменты. Запускает генерацию изображений и видео через MCP. CX Codex +1 ★ 10звёзд репо ComfyUI Builder MIt9 ComfyUI Builder — MCP-сервер для Claude Code, который собирает и запускает графы ComfyUI по запросу. Он передаёт статус генерации через WebSocket без ручной правки JSON. CX Codex +1 ★ 5звёзд репо

Из того же набора10

Весь набор →
comfyui-node-basics Скилл comfyui-node-basics помогает описать структуру пользовательского узла ComfyUI на V3 API, задать его схему и подключить регистрацию. Пригодится при создании узла с нуля или настройке проекта. CX Codex +1 ★ 321звёзд репо comfyui-node-packaging Скилл comfyui-node-packaging для упаковки и публикации кастомных нод ComfyUI: структура проекта, регистрация в __init__.py, requirements.txt, WEB_DIRECTORY. CX Codex +1 ★ 321звёзд репо comfyui-node-outputs Скилл comfyui-node-outputs для Claude Code описывает возврат данных из нод ComfyUI V3: io.NodeOutput, превью изображений, масок, аудио, видео и 3D-моделей. CX Codex +1 ★ 321звёзд репо comfyui-node-lifecycle Скилл comfyui-node-lifecycle объясняет жизненный цикл узлов ComfyUI: порядок выполнения, проверку входов и работу кэша. Пригодится при отладке и разработке пользовательских узлов. CX Codex +1 ★ 321звёзд репо comfyui-node-inputs Скилл comfyui-node-inputs помогает настраивать типы входов и виджеты кастомных узлов ComfyUI. Пригодится при создании числовых полей, выпадающих списков, кривых и видеоредакторов. CX Codex +1 ★ 321звёзд репо comfyui-node-advanced Скилл comfyui-node-advanced для Claude Code помогает проектировать сложные узлы ComfyUI с динамическими входами и сопоставлением типов. Решает задачу узлов, которым недостаточно фиксированной схемы входов. CX Codex +1 ★ 321звёзд репо comfyui-node-datatypes Скилл comfyui-node-datatypes для Claude Code описывает типы входов и выходов нод ComfyUI. Включается при работе с форматами тензоров, моделей, аудио, видео, 3D и виджетов. CX Codex +1 ★ 321звёзд репо comfyui-node-frontend Скилл comfyui-node-frontend помогает создавать JavaScript-расширения для кастомных нод ComfyUI: настраивать хуки жизненного цикла, добавлять DOM-виджеты и менять поведение интерфейса. CX Codex +1 ★ 321звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой