Custom Nodes

---
name: custom-nodes
description: "Implement, inspect, test, and package ComfyUI custom nodes,
  including classic INPUT_TYPES nodes, public comfy_api nodes, hidden inputs,
  async/lazy behavior, output metadata, and API-node credentials."
disable-model-invocation: true
metadata:
  disco-role: operating
license: GPL 3.0
---

# ComfyUI Custom Nodes

Use this sub-skill when the user wants to scaffold, diagnose, inspect, or package ComfyUI node definitions. It covers classic `NODE_CLASS_MAPPINGS` nodes, the public `comfy_api.latest` node API, API-provider nodes, and common execution metadata contracts.

## Route First

- Use `references/node-authoring.md` for classic custom nodes with `INPUT_TYPES`, `RETURN_TYPES`, `FUNCTION`, `CATEGORY`, `NODE_CLASS_MAPPINGS`, and `NODE_DISPLAY_NAME_MAPPINGS`.
- Use `references/public-node-api.md` for `comfy_api.latest.IO.ComfyNode`, `IO.Schema`, typed inputs/outputs, `IO.NodeOutput`, progress updates, node replacement, and public API caveats.
- Use `references/api-nodes.md` for provider-backed nodes that set `is_api_node=True`, use Comfy Org hidden credentials, call proxy endpoints, or need internet/API-key warnings.
- Use `references/troubleshooting.md` when validation fails, a node is missing from the UI, output tuple lengths mismatch, `ANY` causes type confusion, async/lazy validation fails, or API nodes are disabled.
- Use `../workflow-execution/SKILL.md` for prompt graph validation/execution behavior and `../server-api/SKILL.md` for HTTP/websocket transport, API-node server configuration, and credential routing.

## Fast Authoring Checklist

1. Create a Python package or module under ComfyUI's `custom_nodes` loading area with an importable `__init__.py` when using a package.
2. Export `NODE_CLASS_MAPPINGS = {"StableNodeId": NodeClass}`; add `NODE_DISPLAY_NAME_MAPPINGS` for friendly names.
3. Define `INPUT_TYPES` as a `@classmethod` returning `required`, optional `optional`, and optional `hidden` dictionaries.
4. Set `RETURN_TYPES` to a tuple of output type strings; `RETURN_NAMES`, `OUTPUT_IS_LIST`, and `OUTPUT_TOOLTIPS` must align by index when present.
5. Set `FUNCTION` to the exact method name and return a tuple with one item per `RETURN_TYPES`, or a dict with `result`/`ui`/`expand` only when using the supported execution form.
6. Add `CATEGORY`, `DESCRIPTION`, and flags such as `OUTPUT_NODE`, `EXPERIMENTAL`, `DEPRECATED`, or `DEV_ONLY` only when they match behavior.
7. Avoid `IO.ANY` / `"*"` unless the node genuinely accepts arbitrary types; prefer concrete types or multi-types like `FLOAT,INT`.
8. Use hidden inputs deliberately: `PROMPT`, `UNIQUE_ID`, `EXTRA_PNGINFO`, and `DYNPROMPT` are injected by execution and should not be user widgets.

## Bundled Helpers

- `scripts/scaffold_custom_node.py` writes a safe classic custom-node package with required image input, optional strength widget, optional hidden prompt metadata, class mappings, and a tuple-length self-check.
- `scripts/inspect_node_definitions.py` statically inspects one or more Python files for classic node mappings, missing attributes, input/return schema issues, `ANY` usage, hidden inputs, and probable return tuple mismatches.

Both scripts are standalone and safe by default. Run `python scripts/scaffold_custom_node.py --help` or `python scripts/inspect_node_definitions.py --help` from this sub-skill directory for options.