Architecture

How the repository turns agent input into ComfyUI execution.

The architecture is intentionally simple: expose workflows, map a small parameter surface, queue the job, poll for completion, and download images back to local disk.

System Model

Core components

SKILL.md: the agent-facing contract that explains how the skill is discovered and called.
comfyui-skill CLI: the primary interface for discovering, executing, and managing workflows. Install via pip install comfyui-skill-cli.
config.json: multi-server configuration — server URLs, auth, default server.
data/: workflow storage organized by <server_id>/<workflow_id>/.
ui/: optional FastAPI-based local dashboard for visual workflow management.

CLI Commands

What the CLI does

comfyui-skill list: lists enabled workflows and their parameters.
comfyui-skill run / submit: injects args into a workflow, submits the prompt, waits or polls, and downloads images.
comfyui-skill server: manages multi-server configuration (add, remove, enable, disable).
comfyui-skill workflow import: imports workflows from local JSON or ComfyUI server, auto-detects format, and generates schema.
comfyui-skill deps: checks and installs missing custom nodes and models.

Execution Flow

From natural language to image file

The agent calls comfyui-skill list to discover enabled workflows.
The agent resolves user intent into structured args based on the schema.
The CLI maps those args into ComfyUI node fields using schema.json.
The CLI calls native ComfyUI endpoints: /prompt, /history/{prompt_id}, and /view.
Output images are downloaded to local storage and returned to the caller.

Storage Model

How workflows are organized on disk

data/
  <server_id>/
    <workflow_id>/
      workflow.json   # ComfyUI API-format workflow
      schema.json     # Parameter mapping for agents
      history/        # Execution history records

This structure makes workflows portable and easy to inspect. It also gives the repository a clean namespace for multi-server execution.

Why The Schema Layer Matters

ComfyUI graphs are flexible, but agents need contracts

A graph can contain dozens of nodes and many internal fields that should not be exposed directly. The schema layer narrows that surface into a predictable interface with aliases, descriptions, required flags, and types. That is what makes agent calls more reliable and easier to maintain.

Keep exploring

Getting Started Use Cases FAQ