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
/plugin marketplace add jtydhr88/comfyui-custom-node-skills
/plugin install comfyui-custom-nodes@comfyui-custom-node-skillsWhat 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
ComfyExtensionandcomfy_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-skillsThis 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-code3Manually: put the files in place
~/.claude/skills/comfyui-node-basics/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/comfyui-node-basics/
1Skills CLI (Vercel)
npx skills add jtydhr88/comfyui-custom-node-skills --skill comfyui-node-basics -a codex2Manually: put the files in place
.agents/skills/comfyui-node-basics/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jtydhr88/comfyui-custom-node-skills --skill comfyui-node-basics -a cursor2Manually: put the files in place
.cursor/skills/comfyui-node-basics/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jtydhr88/comfyui-custom-node-skills plugins/comfyui-custom-nodes/skills/comfyui-node-basics2Manually: put the files in place
.github/skills/comfyui-node-basics/SKILL.md1Skills CLI (Vercel)
npx skills add jtydhr88/comfyui-custom-node-skills --skill comfyui-node-basics -a gemini-cli2Platform CLI
gemini skills install https://github.com/jtydhr88/comfyui-custom-node-skills --path plugins/comfyui-custom-nodes/skills/comfyui-node-basicsManually: put the files in place
.devin/skills/comfyui-node-basics/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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