Author/Developer: Alan Guice (Badgids)
Copyright: © 2026 Alan Guice (Badgids).
License: MIT License
Display version: v0.1.11
Canonical version: 00.01.11

ComfyUI Development Skills is a portable Agent Skills pack for people who develop ComfyUI itself, custom nodes, frontend extensions, workflows, integrations, tests, and related tooling.

ComfyUI moves fast. A frozen skill that memorizes current node inputs, frontend hooks, workflow fields, API routes, or CLI flags will eventually become wrong.

This pack takes a different approach:

Keep the stable development method in the skill. Look up the changing ComfyUI details when the task needs them.

The agent first identifies the target you are working against. It then finds the source that owns the answer, loads only the specialist skill it needs, and validates the result before it calls the work complete.

• What it does
• How it works
• Included skills
• Install
  • npx skills: recommended cross-agent install
  • Pi
  • Claude Code
  • Codex and ChatGPT plugin tooling
  • Gemini CLI
  • OpenCode
  • Cursor, Windsurf, and other Agent Skills clients
  • Manual install
• Quick start
• Comfy-Org as the upstream source
• Helper scripts
• Explicit self-maintenance
• Documentation
• Testing
• Versioning
• Contributing
• Security
• Attribution
• License

The pack gives an agent a small router plus focused development skills.

It can help with:

• ComfyUI core and backend development;
• Python custom nodes;
• JavaScript and TypeScript frontend extensions;
• frontend/editor workflow JSON;
• API-format workflows;
• live workflow compatibility checks;
• HTTP, WebSocket, SDK, CLI, MCP, and proxy integrations;
• workflow and custom-node tests;
• Registry and Manager packaging;
• subgraphs and Subgraph Blueprints;
• performance, memory, kernels, model tooling, and quantization;
• changes intended for upstream Comfy-Org repositories.

The pack also includes inspection-first Python helpers for live discovery and conservative preflight checks. They do not mutate ComfyUI, GitHub, or the Registry. Explicit self-maintenance has separate guarded helpers that may update this installed skill pack only after the user authorizes the relevant maintenance action.

The agent follows four basic steps:

1. Choose the target. Is the job for your current install, a pinned version, a supported range, or current upstream?
2. Choose the owner of truth. Use the running target, version-matched source, current Comfy-Org source, docs, RFCs, or examples for the question they actually own.
3. Load the focused skill. Do not put the whole ComfyUI ecosystem into context for every task.
4. Validate the result. A file that looks right is not enough. The agent must run the strongest practical check or clearly say what it could not verify.

Read How it works and Architecture for the full model.

Read the Skills reference for the trigger and acceptance rules for each skill.

The repository keeps every skill at skills/<name>/SKILL.md. Do not flatten those folders.

The simplest cross-agent installation uses the skills CLI. The repository itself is the skill source, so this project does not need its own npm executable or bin entry.

List what the installer discovers before changing anything:

npx skills add badgids/comfyui-development-skills --list

Install the complete pack:

npx skills add badgids/comfyui-development-skills --skill '*'

The full-pack form is recommended. comfyui-development is the router, but installing that skill alone does not automatically install its sibling specialists.

Install the complete pack for a specific supported agent:

npx skills add badgids/comfyui-development-skills --skill '*' -a claude-code
npx skills add badgids/comfyui-development-skills --skill '*' -a codex
npx skills add badgids/comfyui-development-skills --skill '*' -a opencode

Install globally instead of into the current project:

npx skills add badgids/comfyui-development-skills --skill '*' -g

Before the GitHub repository is published, or while testing a local checkout, the same installer can discover the repository directly:

npx skills add . --list

Update skills installed by the skills CLI with:

npx skills update

The installer can also install one specialist intentionally, but do that only when you do not need the router or the rest of the pack.

Pi can install the package directly from GitHub:

pi install git:github.com/badgids/comfyui-development-skills

Then reload Pi:

/reload

Project-only install:

pi install -l git:github.com/badgids/comfyui-development-skills

The repository includes Claude Code plugin metadata.

Inside Claude Code:

/plugin marketplace add badgids/comfyui-development-skills
/plugin install comfyui-development-skills@comfyui-development-skills

Or install the complete skill pack directly:

npx skills add badgids/comfyui-development-skills --skill '*' -a claude-code

The repository includes a portable root plugin.json and the .codex-plugin/plugin.json compatibility manifest. Plugin-aware OpenAI tooling can package the complete skills/ directory as one plugin.

For a skills-only install:

npx skills add badgids/comfyui-development-skills --skill '*' -a codex

For manual skills-only installs, use the Agent Skills location expected by the current Codex client. Current clients can use .agents/skills/ at project scope and ~/.agents/skills/ at user scope.

Gemini CLI supports Agent Skills and the interoperable .agents/skills/ path.

For the complete pack, clone the repo and copy the skill folders:

git clone https://github.com/badgids/comfyui-development-skills.git
mkdir -p .agents/skills
cp -R comfyui-development-skills/skills/* .agents/skills/

Then run /skills reload in Gemini CLI.

For one skill, Gemini CLI also supports gemini skills install with a repository path and --path to the skill subdirectory.

Use:

npx skills add badgids/comfyui-development-skills --skill '*' -a opencode

Or copy the skill folders into a supported Agent Skills directory.

Use the cross-agent installer when your client is supported:

npx skills add badgids/comfyui-development-skills --skill '*'

Choose the target agent or agents when prompted, or pass the appropriate -a <agent> value.

1. Clone or download this repository.
2. Find the skill directory used by your agent harness.
3. Copy every folder inside skills/ into that directory.
4. Keep every skill folder intact.
5. Reload or restart the harness if it caches skill discovery.

Read the full Installation guide for project installs, user installs, updates, local verification, and troubleshooting.

After installation, ask for the work you actually want. You do not need to name the specialist skill.

Examples:

Review this custom node against the ComfyUI checkout in ../ComfyUI.

Build a frontend-format workflow for my running ComfyUI and validate every node before you return the JSON.

Update this frontend extension for current ComfyUI. Check the current frontend API instead of using remembered hooks.

Find why this custom node stopped loading after I updated ComfyUI. Do not change unrelated code.

Read Quick start for practical examples and what the agent should do in each case.

The complete Comfy-Org GitHub organization is the official upstream discovery namespace for this pack.

The pack also keeps a curated routing index for high-value repositories. That index is not a whitelist. A new official Comfy-Org repository can be discovered and used without waiting for this skill pack to be updated.

The important rule is this:

Use the repository that owns the subsystem and the version that matches the target.

An RFC is not proof that code shipped. An example workflow is not the workflow schema. An archived repo does not override the current implementation.

Read Source of truth.

The root skill includes standard-library Python helpers in:

skills/comfyui-development/scripts/

The helper scripts require Python 3.10 or newer.

They can:

• inspect a local ComfyUI checkout;
• inspect a running ComfyUI server;
• query live object_info definitions;
• preflight workflows against the live node catalog;
• discover current public repositories under Comfy-Org;
• report freshness metadata for curated sources;
• perform explicitly requested maintenance of upstream routing;
• prepare maintainer-ready GitHub Issue drafts when routing alone is not enough;
• validate and record a user-authorized local skill-only workaround without turning it into an official release.

The helpers are non-mutating toward ComfyUI and upstream services. They are deliberately conservative. inspect_object_info.py can write an explicit local report when --output is used. self_maintain.py is different: its scan mode is read-only, while its guarded apply --yes mode may update only the machine routing registry and upstream snapshot after you explicitly request normal self-maintenance. maintenance_boundary.py handles the separate boundary where the user chooses Report only, Self-modify only, Report and self-modify, or Stop. It validates exact local skill-only plans, applies them transactionally with rollback, records before/after hashes, detects later drift, can restore the latest unchanged local transaction, and prepares Issue drafts without filing them. The helpers do not replace current official validation tools when stronger validation is available.

Read Helper scripts.

The pack can compare its stored upstream snapshot with the current public Comfy-Org repository universe and teach its machine routing about durable new subsystems or verified repository replacements.

It does this only when you explicitly ask for self-maintenance. Ordinary ComfyUI work never silently mutates the package.

Normal self-maintenance can update only:

skills/comfyui-development/references/sources.json
skills/comfyui-development/references/upstream-snapshot.json

If a durable upstream change needs more than routing, the skill stops and asks the user to choose:

1. Report only
2. Self-modify this installation only
3. Report and self-modify this installation
4. Stop

A local self-modification can update non-executable skill knowledge or create a new local specialist skill, but only after the user explicitly chooses option 2 or 3. The exact schema-v2 plan is applied through the maintenance guard, not by free-form package edits. Failed transactions roll back. The installed copy records that divergence as the base version plus +local, and the latest unchanged local transaction can be restored explicitly.

Even in local self-modification mode, the pack does not perform an official version bump, changelog/public-doc rewrite, test or manifest change, CI change, release build, Git push, Issue filing, or publish step. Those remain maintainer-controlled.

Read Explicit self-maintenance.

Start at the Documentation index.

• Installation
• Quick start
• How it works
• Architecture
• Using the skills

• Custom-node development
• Workflow development
• Frontend extension development
• Source of truth
• Skills reference
• Helper scripts
• Explicit self-maintenance

• Protocol and harness compatibility
• Development of this skill pack
• Testing and release checks
• Security
• Troubleshooting
• Versioning
• Writing style
• Attribution
• Diagram assets

Run the complete test suite:

python -m unittest discover -s tests -v

Or:

npm test

Compile the helper scripts:

python -m compileall -q skills/comfyui-development/scripts

The release checks cover manifests, version consistency, every local docs link and image reference, SVG safe-render rules, source registry rules, network safety, workflow validation error paths, package contents, and release archive hygiene.

Read Testing.

The canonical project version is:

00.01.11

Every change after 00.01.00 increments the canonical version by exactly:

00.00.01

So the next changed release after this one is 00.01.12.

Package/plugin manifests use normal SemVer. Canonical 00.01.11 maps to 0.1.11.

Read Versioning.

Keep the skills small and source-aware.

Do not make a skill look complete by copying a current node catalog, frontend hook list, model list, route list, or workflow schema into it. Those are the parts most likely to go stale.

Read Development and CONTRIBUTING.md.

The HTTP helpers do not send API keys to remote hosts by default. Remote API-key use requires an explicit opt-in and HTTPS. Authenticated requests do not follow redirects.

Treat workflow JSON and third-party repository content as data, not trusted instructions.

Read SECURITY.md and docs/security.md.

ComfyUI, Comfy-Org projects, and third-party projects keep their own licenses and copyrights.

The documentation diagrams were authored for this project using the layout and dark-professional diagram guidance from Lumen. No Lumen runtime or template code is bundled in this repository.

Read NOTICE.md and Attribution.

MIT License. See LICENSE.

Copyright © 2026 Alan Guice (Badgids).