How the repository turns agent input into ComfyUI execution.

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.
• official local Comfy MCP: the optional live interface for templates, nodes, models, validation, jobs, and ComfyUI lifecycle operations.
• scripts/comfy_mcp.py: a fallback stdio bridge for shell-only Agent hosts; native host MCP tools remain preferred.
• 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.

Application Routing

CLI for known work, MCP for live decisions

• CLI route: registered workflows, repeated execution, batch jobs, uploads, and history.
• MCP route: current template, node, and model discovery; raw-workflow validation; template adaptation; and lifecycle control.
• Single-submit rule: after either route returns a prompt_id, status and outputs stay on that route so one request cannot generate twice.

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

1. The agent calls comfyui-skill list to discover enabled workflows.
2. The agent resolves user intent into structured args based on the schema.
3. The CLI maps those args into ComfyUI node fields using schema.json.
4. The CLI calls native ComfyUI endpoints: /prompt, /history/{prompt_id}, and /view.
5. 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.

Related Pages

Keep exploring