agentleFS
badgidsbadgids/comfyui-development-skills/skills/comfyui-custom-node-backend/SKILL.md

comfyui-custom-node-backend

Skill4 starsChanged 44 days agoMITView on GitHub

Use when creating, modifying, migrating, debugging, or reviewing ComfyUI Python custom nodes or custom-node packs, including schemas, execution methods, registration, inputs/outputs, validation, caching/change detection, UI results, dependencies, and node-pack structure.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 10 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the comfyui-development router skill is installed, apply its compatibility and source-authority policy.

    line 9
  2. Distinctive:

    Do not turn a small bug fix into a migration unless migration is necessary.

    line 35
  3. Distinctive:

    Do not assume the current or legacy custom-node definition style from memory.

    line 43
  4. Very specific:

    If using a versioned comfy_api, inspect which versions actually exist in the target and what the official docs call stable/development …

    line 47
  5. Distinctive:

    Search current official source for a comparable built-in node or datatype.

    line 53
  6. Distinctive:

    Verify input/output type semantics from current target source.

    line 54
  7. Distinctive:

    Keep execution logic independent of UI assumptions where possible.

    line 56
  8. Distinctive:

    Add validation/change-detection behavior only when it is required and verify its current contract.

    line 57
  9. Very specific:

    If dependency isolation is part of the design, inspect the current pyisolate contract and the target ComfyUI integration before inventing a …

    line 58
  10. Very specific:

    If frontend behavior is needed, also use the comfyui-frontend-extension skill rather than guessing JS hooks.

    line 59
  11. Distinctive:

    Run a minimal representative workflow when feasible.

    line 63
  12. Distinctive:

    When supporting multiple ComfyUI generations, make compatibility behavior explicit and testable.

    line 71
  13. Distinctive:

    Before calling the node or pack complete:

    line 79
  14. Distinctive:

    run a minimal representative workflow when practical.

    line 85

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ComfyUI Custom Node Backend

If the comfyui-development router skill is installed, apply its compatibility and source-authority policy. In all cases, read the relevant current custom-node documentation before implementation.

Source set

Use as needed:

  • the target ComfyUI checkout and live node catalog;
  • Comfy-Org/docs custom-node documentation;
  • Comfy-Org/ComfyUI bundled/current node examples and comfy_api implementation;
  • Comfy-Org/cookiecutter-comfy-extension for current project/package conventions;
  • Comfy-Org/pyisolate when dependency conflicts, isolated extension environments, subprocess/RPC isolation, sandboxing, or cross-process tensor sharing are relevant;
  • target pack source and tests;
  • official test/QA tools.

First classify the work

Determine whether this is:

  • a new node in a new pack;
  • a new node in an existing pack;
  • a bug fix;
  • a compatibility fix;
  • an API-generation migration;
  • a packaging/import problem;
  • a backend half of a frontend-connected extension.

Do not turn a small bug fix into a migration unless migration is necessary.

Current official agent guidance

If the target workflow uses comfy-cli or its installed agent skills, inspect the current/version-matched comfy-cli skill set before relying on CLI-specific custom-node advice. Its bundled custom-node guidance is useful operational synthesis, but verify node API contracts against the target ComfyUI source/docs and live registration. Do not copy that upstream skill into this pack.

Node-definition rule

Do not assume the current or legacy custom-node definition style from memory.

For a new node, inspect current official guidance and target compatibility requirements. For an existing node, identify the style already used by the project and whether its supported ComfyUI range requires it.

If using a versioned comfy_api, inspect which versions actually exist in the target and what the official docs call stable/development before choosing an import.

Implementation procedure

  1. Inspect the repository structure, dependency metadata, and existing nodes.
  2. Identify the target ComfyUI/API generation.
  3. Search current official source for a comparable built-in node or datatype.
  4. Verify input/output type semantics from current target source.
  5. Implement node schema/registration using the target's real contract.
  6. Keep execution logic independent of UI assumptions where possible.
  7. Add validation/change-detection behavior only when it is required and verify its current contract.
  8. If dependency isolation is part of the design, inspect the current pyisolate contract and the target ComfyUI integration before inventing a custom isolation mechanism. Do not assume the target uses pyisolate merely because it is an official project.
  9. If frontend behavior is needed, also use the comfyui-frontend-extension skill rather than guessing JS hooks.
  10. Add focused tests.
  11. Load the node in ComfyUI and confirm it registers.
  12. Inspect the live node definition and compare it with the intended public interface.
  13. Run a minimal representative workflow when feasible.

Registration gate

A Python file importing successfully is not sufficient. Confirm the node pack is actually discovered and the intended nodes appear in the running target.

Compatibility gate

When supporting multiple ComfyUI generations, make compatibility behavior explicit and testable. Do not use broad exception swallowing to make imports appear compatible.

Packaging handoff

For Registry/Manager packaging or publishing, also use the comfyui-packaging-and-registry skill.

Acceptance gate

Before calling the node or pack complete:

  • confirm the intended node registration contract against the target ComfyUI generation;
  • pass focused tests for the changed behavior;
  • load the pack in the target when practical and confirm the intended nodes register;
  • compare the exposed live node interface with the intended inputs and outputs;
  • run a minimal representative workflow when practical;
  • state clearly when a live registration or workflow check could not be run.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.