comfyui-development
Skill4 starsChanged 44 days agoMITView on GitHub
Use for any task that creates, modifies, debugs, validates, tests, packages, publishes, or reviews ComfyUI code, custom nodes, frontend extensions, workflows, subgraphs, API clients, SDK integrations, CI, or performance behavior. This root skill routes the task to focused specialist skills and requires live or version-matched verification before volatile ComfyUI details are treated as current.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- comfyui-api-and-sdkSkill
- comfyui-core-runtimeSkill
- comfyui-custom-node-backendSkill
- comfyui-frontend-extensionSkill
- comfyui-packaging-and-registrySkill
- comfyui-performanceSkill
- comfyui-self-maintenanceSkill
- comfyui-subgraphsSkill
- comfyui-testing-and-qaSkill
- comfyui-upstream-developmentSkill
- comfyui-workflowsSkill
- comfyui-workflow-validationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
33 rules. About 0 are common, 25 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Never rely on remembered ComfyUI implementation details when they can be verified from the target installation, a version-matched checkout, …
- Distinctive: line 40
Before coding, determine which target applies.
- Very specific: line 47
Read references/compatibility-policy.md when the target is not trivial.
- Very specific: line 51
Read references/authority-policy.md before resolving a source conflict and references/upstream-discovery.md when choosing or discovering an …
- Very specific: line 55
Check references/sources.json for a matching machine route.
- Distinctive: line 66
Read only the specialist skill or skills needed for the task.
- Very specific: line 85
Never activate comfyui-self-maintenance during ordinary development simply because a new repo or feature is discovered.
- Distinctive: line 93
Before using a volatile ComfyUI fact:
- Distinctive: line 95
Prefer the target checkout or running target if available.
- Very specific: line 96
Check references/sources.json for a matching route, its status, any superseded_by authority move, and any specialist hint.
- Very specific: line 97
Use references/source-map.md as the curated human guide for common repositories.
- Very specific: line 98
If neither map clearly covers the task, search the entire current Comfy-Org organization for the repository that owns the behavior.
- Distinctive: line 99
Read the surrounding implementation, not just a search-result snippet.
- Distinctive: line 100
If documentation and implementation disagree, determine whether they refer to different versions.
- Very specific: line 103
Use references/search-recipes.md for practical search patterns.
- Distinctive: line 107
When the task concerns a particular running ComfyUI installation, query the running server rather than assuming its node catalog.
- Distinctive: line 121
Do not assume a custom node exists because it exists online.
- Distinctive: line 125
Never invent any of the following to make a solution look complete:
- Distinctive: line 138
If authoritative discovery is unavailable, state exactly what remains unverified and keep the result clearly provisional.
- Distinctive: line 142
When editing an existing project:
- Distinctive: line 146
do not modernize unrelated code merely because a newer API exists.
- Distinctive: line 147
do not migrate V1 nodes to V3 unless migration is requested or necessary for the actual target.
- Distinctive: line 148
do not downgrade a V3 implementation to V1 simply because V1 is familiar.
- Distinctive: line 149
keep changes scoped and inspect the surrounding project conventions first.
- Distinctive: line 153
Do not declare ComfyUI code or a workflow correct solely because it is syntactically plausible.
- Distinctive: line 155
Use the strongest validation available for the task:
- Distinctive: line 171
Before finishing a substantial task, be able to answer internally:
- Distinctive: line 186
Do not dump this receipt mechanically to the user.
- Distinctive: line 200
Before calling ComfyUI work complete:
- Distinctive: line 203
use the specialist skill or source set that owns the task.
- Distinctive: line 204
verify volatile ComfyUI facts from the target or current/version-matched official sources.
- Distinctive: line 205
run the strongest practical validation for the change.
- Distinctive: line 207
do not invent nodes, sockets, hooks, routes, schemas, CLI flags, model names, or package requirements.
≈ “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.
Files
ComfyUI Development
This is the root router for ComfyUI development work.
ComfyUI changes quickly. Treat remembered implementation details as hints, not authority. The durable knowledge in this pack is where to find truth, how to resolve conflicting sources, how to identify the compatibility target, and how to validate the result.
Core rule
Never rely on remembered ComfyUI implementation details when they can be verified from the target installation, a version-matched checkout, or current official Comfy-Org sources. Treat the entire Comfy-Org GitHub organization as the canonical upstream discovery namespace.
Safe to retain as durable knowledge:
- official source locations and their roles;
- source precedence and conflict-resolution rules;
- discovery procedures;
- validation procedures;
- task-routing rules;
- general engineering principles that do not depend on a particular ComfyUI release.
Volatile facts that must be verified before use:
- node schemas, inputs, outputs, widgets, datatypes, and enum values;
- workflow schema versions and fields;
- frontend extension hooks and frontend internals;
- server routes, payload formats, WebSocket messages, and SDK surfaces;
comfy_apiversions and imports;- CLI command spelling and flags;
- packaging and registry metadata requirements;
- internal module paths, classes, function signatures, and behavior;
- supported models, loaders, filenames, and custom-node interfaces.
First decision: identify the compatibility target
Before coding, determine which target applies. Do not silently substitute current upstream for a local or pinned target.
- Target installation: the user's running/local ComfyUI and installed custom nodes are the compatibility target.
- Pinned target: a named tag, release, branch, commit, dependency range, or repository lockfile is the target.
- Project range: the project declares a supported ComfyUI range and changes must preserve that range.
- Current upstream: the user explicitly wants current ComfyUI behavior or no older target exists and the task is forward development.
Read references/compatibility-policy.md when the target is not trivial.
Source order
Read references/authority-policy.md before resolving a source conflict and references/upstream-discovery.md when choosing or discovering an official upstream repository.
Short version:
- Check
references/sources.jsonfor a matching machine route. For current-upstream work, followsuperseded_bywhen a route is markedsuperseded; do not promote historical/archived routes over their current replacement. - For what runs on this installation, the live installation wins.
- For how a pinned/local version is implemented, that version's source wins.
- For current supported public behavior, current official docs plus corresponding current source are primary.
- For frontend implementation, use the official frontend repository and current frontend docs.
- For future or proposed architecture, RFCs are evidence of proposals, not shipped behavior.
- Official examples and templates show patterns, but do not override schemas, runtime introspection, or implementation source.
- Community code is supplementary evidence only unless the task is specifically about that project.
Route the task
Read only the specialist skill or skills needed for the task.
| Task | Specialist skill |
| ComfyUI core, execution, server, internals | comfyui-core-runtime |
| Python custom node or node pack | comfyui-custom-node-backend |
| JS/TS frontend extension, widget, UI behavior | comfyui-frontend-extension |
| Create or edit a workflow | comfyui-workflows |
| Diagnose or validate a workflow | comfyui-workflow-validation |
| REST/WebSocket/API client, SDK, MCP, proxy | comfyui-api-and-sdk |
| Tests, QA, CI | comfyui-testing-and-qa |
| Package, publish, Registry, Manager | comfyui-packaging-and-registry |
| Subgraphs or blueprint work | comfyui-subgraphs |
| Benchmarking, kernels, performance | comfyui-performance |
| Upstream contribution, RFC-adjacent work | comfyui-upstream-development |
| Explicitly requested maintenance of this pack's upstream snapshot/source routing | comfyui-self-maintenance |
Activate specialist skills through the harness's normal skill mechanism. Do not traverse outside this skill directory to read sibling SKILL.md files. If a harness cannot activate another skill from an active skill, start with the specialist skill directly from the harness's discovered skill list.
Never activate comfyui-self-maintenance during ordinary development simply because a new repo or feature is discovered. Ordinary discovery stays read-only. Use self-maintenance only when the current user explicitly asks the pack to maintain its own routing or upstream snapshot.
A specialist field learned through explicit self-maintenance is a routing hint to an existing skill. Use it when it matches the actual task, but do not let it override a more specific task classification or the compatibility target.
For work crossing boundaries, load the minimum combination. Example: a custom node with a frontend widget normally needs custom-node-backend plus frontend-extension, then testing-and-qa before completion.
Mandatory discovery behavior
Before using a volatile ComfyUI fact:
- Prefer the target checkout or running target if available.
- Check
references/sources.jsonfor a matching route, itsstatus, anysuperseded_byauthority move, and anyspecialisthint. - Use
references/source-map.mdas the curated human guide for common repositories. - If neither map clearly covers the task, search the entire current
Comfy-Orgorganization for the repository that owns the behavior. - Read the surrounding implementation, not just a search-result snippet.
- If documentation and implementation disagree, determine whether they refer to different versions.
- Record enough provenance to explain what was checked: repository/path and, when relevant, commit or installed version.
Use references/search-recipes.md for practical search patterns. When the task uses Comfy-Org agent tooling, comfy-cli, or an upstream repository's own agent instructions, read references/official-agent-guidance.md. Do not vendor or blindly merge upstream prompt/skill files into this package.
Live runtime discovery
When the task concerns a particular running ComfyUI installation, query the running server rather than assuming its node catalog.
The helper scripts in scripts/ can probe a local or remote target without third-party Python dependencies:
discover_comfy_org.pyinspect_comfy_environment.pyinspect_object_info.pyvalidate_workflow.pysource_freshness.pyself_maintain.pymaintenance_boundary.py
The scripts probe documented/current endpoints with fallbacks rather than treating one URL shape as permanent. self_maintain.py scan is read-only. Its apply --yes mode is reserved for explicitly requested normal self-maintenance and may modify only references/sources.json and references/upstream-snapshot.json. If maintenance discovers that broader skill knowledge is required, activate comfyui-self-maintenance and present its four explicit boundary choices. maintenance_boundary.py validates any user-authorized local skill-only plan, records local divergence, and prepares maintainer Issue drafts without filing them.
Do not assume a custom node exists because it exists online. Do not assume its installed version matches upstream.
No fabrication rules
Never invent any of the following to make a solution look complete:
- node class names;
- input or output sockets;
- widget order;
- model filenames;
- schema fields;
- frontend hooks;
- API routes;
- CLI options;
- Registry metadata;
- package versions.
If authoritative discovery is unavailable, state exactly what remains unverified and keep the result clearly provisional.
Modification rules
When editing an existing project:
- preserve existing filenames and paths unless the task requires changing them;
- preserve compatibility behavior unless the task explicitly changes it;
- do not modernize unrelated code merely because a newer API exists;
- do not migrate V1 nodes to V3 unless migration is requested or necessary for the actual target;
- do not downgrade a V3 implementation to V1 simply because V1 is familiar;
- keep changes scoped and inspect the surrounding project conventions first.
Validation gate
Do not declare ComfyUI code or a workflow correct solely because it is syntactically plausible.
Use the strongest validation available for the task:
- syntax/static checks;
- current schema validation;
- import/load checks;
- live node registration inspection;
- frontend build/type checks;
- unit tests;
- workflow preflight against live node definitions;
- representative integration workflow;
- official QA/test tools where appropriate.
A validation tool failing to run is not a passing result. Report it as an unverified gate.
Completion receipt
Before finishing a substantial task, be able to answer internally:
Compatibility target:
Target commit/version discovered:
Running server inspected:
Live node catalog inspected:
Official docs consulted:
Core source consulted:
Frontend source consulted:
Examples/templates consulted:
Validation performed:
Remaining uncertainty:Do not dump this receipt mechanically to the user. Use it to prevent unsupported claims and surface only the parts that matter.
Source registry
references/sources.json is the machine-readable curated routing registry of high-value official repositories known to this pack. It is not an exhaustive allowlist. Optional status, superseded_by, and specialist fields record authority moves without erasing historical compatibility context.
references/upstream-snapshot.json is a baseline of the public Comfy-Org repository universe used only to detect upstream changes during explicitly requested self-maintenance. It is not authority by itself.
references/source-map.md explains which repositories answer which kinds of questions, and references/upstream-discovery.md defines how to discover and classify any other current repository under Comfy-Org.
The authoritative upstream search universe is the entire Comfy-Org organization. Discover newly relevant official repositories whenever necessary; absence from sources.json does not make an official repository ineligible.
Acceptance gate
Before calling ComfyUI work complete:
- identify the compatibility target;
- use the specialist skill or source set that owns the task;
- verify volatile ComfyUI facts from the target or current/version-matched official sources;
- run the strongest practical validation for the change;
- report any validation step that could not be run;
- do not invent nodes, sockets, hooks, routes, schemas, CLI flags, model names, or package requirements.
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
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.

