ComfyUI Skill Public

https://github.com/zambav/comfyui-agent-toolkit
Admin
ComfyUI Skill Public provides a portable, installation-agnostic operating model for ComfyUI,...
Tokens:26,031
Snippets:329
Trust Score:4.6
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### ComfyUI Agent Toolkit Quick Start Installation

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Provides bash commands to clone the repository, navigate into the directory, and install necessary Python dependencies for running the toolkit.

```bash
# 1. Drop the skill into your agent's environment
git clone https://github.com/Zambav/comfyui-skill-public.git
cd comfyui-skill-public

# 2. Read the right entry point
#    - AI agent       -> AGENTS.md
#    - Human operator -> SKILL.md

# 3. (Optional) Copy the production helper into your project
cp scripts/api_lib.py /path/to/your/project/

# 4. Install runtime dependencies
pip install requests websocket-client pillow
```

--------------------------------

### JoyCaption File Naming Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

An example illustrating the naming variants for an input folder named `Render Dump`.

```text
- Render Dump/joycaption.md
- Render Dump/joycaption_render_dump.md
- Render Dump/joycaption_mandalorian_scene.md
```

--------------------------------

### I2V Portrait Motion Example Prompt

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/wan-2.2-prompting-guide.md

An example prompt for Image-to-Video (I2V) portrait generation, specifying subject, environment, motion, camera, lighting, and temporal evolution.

```text
A young chef stands in a warm kitchen, wearing a white apron and dark shirt.
She looks down at the plated dish, then slowly raises her gaze toward camera.
The camera performs a gentle push-in from medium shot to medium close-up.
Soft tungsten lighting reflects on stainless steel surfaces, with subtle steam movement in the background.
By the end of the clip, her expression shifts from focused to satisfied.
```

--------------------------------

### Product Hero Prompt Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/flux-2-prompting-guide.md

Example prompt for a product hero shot, detailing the product, surface, camera angle, background, lighting, and style.

```text
Premium black smartwatch on a brushed aluminum surface, angled three-quarter view,
clean gradient studio background, softbox highlights on the glass, crisp engraved edge detail,
luxury tech advertisement style, high realism.
```

--------------------------------

### Output Folder Naming Convention Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/batch-operations.md

Illustrates the relative output folder structure for batch operations, keeping source images and outputs together. This example shows the formula for defining input and batch-related paths.

```shell
input_folder = "/path/to/your/portraits"
batch_root   = "/path/to/your/portraits/portraits flux edit batch"
batch_01     = "/path/to/your/portraits/portraits flux edit batch/batch_01"
```

--------------------------------

### T2V Atmospheric Scene Example Prompt

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/wan-2.2-prompting-guide.md

An example prompt for Text-to-Video (T2V) atmospheric scene generation, detailing the scene, action, camera movement, lighting, and temporal progression.

```text
A narrow rainy street in Tokyo at night with neon signs and reflective pavement.
A cyclist enters frame from the left and rides steadily toward the center while pedestrians pass in the background.
Camera tracks right at a slow, stable pace, maintaining a cinematic wide shot.
Blue-magenta neon lighting and wet-surface reflections dominate the mood.
As the clip progresses, light rain intensifies slightly and distant headlights bloom through mist.
```

--------------------------------

### Controlled Edit Instruction Prompt Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/flux-2-prompting-guide.md

Example prompt for image editing, specifying elements to preserve and changes to make, such as lighting and style.

```text
Preserve the original room layout and furniture placement, replace daytime lighting with warm sunset light
through the window, add soft shadow direction on the floor, keep image natural and photorealistic,
no stylized illustration look.
```

--------------------------------

### JoyCaption Markdown Format Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

This example shows the standard Markdown format for a single image description within a `joycaption.md` file. It includes the required heading format and a single descriptive paragraph.

```markdown
## filename.jpg

A wide establishing shot of an alien canyon at golden hour. Rust-red rock
formations tower on both sides, casting long shadows across the sandy canyon
floor. A small figure stands near the left edge for scale. Dust motes catch the
warm low-angle light. Hazy atmosphere fades to pale orange at the horizon.
```

--------------------------------

### Example Prompt Skeleton

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/wan-2.2-prompting-guide.md

A skeleton structure for video generation prompts, detailing the key components to include for a comprehensive description.

```text
[A subject] in [environment] [performs motion], camera [movement/framing],
with [lighting/mood], action evolves as [timeline cue].
```

--------------------------------

### Install Dependencies for ComfyUI API

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Install the necessary Python packages for interacting with the ComfyUI API.

```bash
pip install requests websocket-client
```

--------------------------------

### Negative Prompt Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

A concise example of a negative prompt. Use sparingly and specifically to guide the model without overwhelming it with synonyms.

```text
"avoid locked-off static frame as sole camera behaviour, frozen motion, still photography, cartoonish"
```

--------------------------------

### Cinematic Portrait Prompt Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/flux-2-prompting-guide.md

Example prompt for generating a cinematic portrait, specifying subject details, environment, lighting, and mood.

```text
A 35-year-old woman standing under a neon storefront awning at night, medium close-up,
rain droplets visible on her leather jacket, shallow depth of field, soft magenta and cyan rim lighting,
subtle film grain, realistic skin texture, cinematic urban mood.
```

--------------------------------

### ComfyUI API Usage Pattern Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Demonstrates a typical workflow for using the `ComfyUI` class to queue prompts and wait for their completion. This pattern involves initializing the client, establishing a WebSocket connection, building a workflow, queuing the prompt, and handling potential errors.

```python
client = ComfyUI(host="http://127.0.0.1:8188")

# One-time setup per batch run
client_id = str(uuid.uuid4())
ws = websocket.WebSocket()
ws.connect(f"{client.ws}/ws?clientId={client_id}")

try:
    for image_path in images:
        filename = copy_to_comfyui_input(image_path, comfyui_input_dir)
        seed     = random.randint(0, 2**32 - 1)
        wf       = build_flux_workflow(filename, prompt, seed, output_dir, save_prefix, base_path)
        prompt_id = client.queue_prompt(wf, client_id)
        client.wait_for_completion(prompt_id, ws)
        print(f"OK: {image_path}")
finally:
    ws.close()
```

--------------------------------

### Natural Language Interaction Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Illustrates a conversational exchange between a user and the agent for batch image processing. The agent clarifies requirements and confirms job execution.

```text
You:    "batch this entire image folder into cinematic portraits and pick good prompts"
Agent:  "Where are the photos? Where should outputs go? What should I call this batch?"
You:    "D:/photos/portraits, D:/photos/portraits/cinematic, 'portraits_v1'"
Agent:  "47 images found. Running FLUX 2 image edit, one prompt, randomized seed."
         [.. 47 jobs queued, each one blocks on completion, each one verified with /history ..]
Agent:  "Done. 47/47 OK. Output: D:/photos/portraits/cinematic/batch_01/"
```

--------------------------------

### Discord Start Ping Format

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/cron-jobs.md

This message format is sent immediately when a cron job is created to indicate the start of a batch process.

```text
Started {job_name} — {N} images x {B} pass(es) | Output: {output_path} | ETA: ~{eta}
```

--------------------------------

### Camera Intent Examples

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/demo-workflows/ltx 2.3/LTX 2.3 Prompting Guide.txt

Include short phrases to give the output more direction regarding camera movement and framing.

```text
slow push-in
fixed frame
side tracking shot
handheld movement
slow dolly in
```

--------------------------------

### Prompt Versioning JSON Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

Example JSON structure for managing prompt versions, including version details and image-specific prompts. Use a new `_version` block for re-generating prompts with updated cinematic direction.

```json
{
  "_version": {
    "v": 1,
    "description": "Initial cinematic pass -- outdoor scenes, warm lighting",
    "date": "2026-04-01",
    "negative": "avoid locked-off static frame as sole camera behaviour, frozen motion, still photography, cartoonish"
  },
  "image_001.jpg": {
    "prompt": "The camera slowly tracks right as the subject walks forward...",
    "description": "Person walking on cobblestone street at golden hour"
  }
}
```

--------------------------------

### Install Python Packages with Pip

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/dependencies.md

Installs essential Python packages for interacting with ComfyUI's REST API and handling real-time events. Pillow is used for image file handling.

```bash
pip install requests websocket-client pillow
```

--------------------------------

### Generate Image Captions with JoyCaption CLI

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/dependencies.md

Uses the JoyCaption CLI tool to generate natural language descriptions of images. Ensure the model and mmproj paths are correctly set for your JoyCaption installation.

```bash
llama-mtmd-cli \
  --model /path/to/joycaption/model.bin \
  --mmproj /path/to/joycaption/mmproj.bin \
  --image path/to/image.jpg \
  --caption
```

--------------------------------

### Example Job State File Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/batch-operations.md

This JSON structure represents the state of a batch job, including metadata, input/output paths, and individual job statuses. It is saved alongside the run script for persistence.

```json
{
  "batch_name": "earth_maze_v2",
  "input_folder": "/path/to/your/earth_maze",
  "workflow_file": "Flux 2 Image edit workflow API.json",
  "created_at": "2026-04-01T03:00:00Z",
  "jobs": [
    {
      "label": "earth_maze_00001.jpg",
      "image_path": "/path/to/your/earth_maze/earth_maze_00001.jpg",
      "batch_prompt": "enhance realism, cinematic lighting",
      "seed": 1234567890,
      "output_dir": "/path/to/your/earth_maze/earth_maze flux edit batch/batch_01",
      "save_prefix": "earth_maze_",
      "status": "success",
      "prompt_id": "abc123",
      "submitted_at": "2026-04-01T03:00:05Z",
      "completed_at": "2026-04-01T03:01:12Z",
      "error": null
    }
  ]
}
```

--------------------------------

### Portable ComfyUI Configuration Template

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/setup.md

A YAML template for storing ComfyUI installation-specific values. Replace example defaults with actual environment details. Track essential information like URLs, custom nodes, model aliases, output rules, and hardware notes.

```yaml
comfyui:
  base_url: http://127.0.0.1:8188
  websocket_url: ws://127.0.0.1:8188/ws
  install_type: local   # local | remote | cloud
  version_notes: ""
  custom_nodes:
    - name: ""
      purpose: ""
  model_aliases:
    image_default: ""
    video_default: ""
    flux_default: ""
    wan_default: ""
    ltx_default: ""
  output_rules:
    default_subfolder: ""
    filename_prefix: ""
  hardware:
    gpu: ""
    vram_gb: ""
    notes: ""
```

--------------------------------

### Prompt Order Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Organize your prompt elements in a consistent order for better readability and easier refinement. This structure guides the model effectively.

```text
Subject -> action -> camera -> mood
```

--------------------------------

### Create ComfyUI Batch Monitor Cron Job

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/cron-jobs.md

Adds a new cron job to monitor ComfyUI batch progress. This example uses OpenClaw syntax and includes parameters for naming, interval, message content, notification destination, session isolation, and timeout.

```bash
# OpenClaw example -- substitute your scheduler's equivalent
openclaw cron add \
  --name "ComfyUI Batch Monitor -- {job_name}" \
  --every "30m" \
  --message "Check {batch_name} status: {output_path} -- count outputs and check for errors" \
  --announce --to "{notification_destination}" --channel "{channel_type}" \
  --session "isolated" --timeout-seconds 60
```

--------------------------------

### ComfyUI Class Reference Implementation

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

This class provides a direct, inline reference for interacting with the ComfyUI API. It is suitable for quick tests, throwaway scripts, learning examples, or when module imports are awkward, such as in notebooks. It offers methods for checking API liveness, retrieving object information, queuing prompts, waiting for job completion, and managing the queue.

```APIDOC
## ComfyUI Class

### Description
Provides methods to interact with the ComfyUI API, including prompt queuing, status checking, and history retrieval.

### Methods

#### `__init__(self, host: str = "http://127.0.0.1:8188", ws_host: str = "ws://127.0.0.1:8188")`
Initializes the ComfyUI client with host and WebSocket host URLs.

#### `is_alive(self) -> bool`
Checks if the ComfyUI API is accessible and responsive.

#### `object_info(self) -> dict`
Retrieves detailed information about all available nodes and their properties.

#### `get_node_class(self, node_name: str) -> dict | None`
Gets the details for a specific node class by its name.

#### `queue_prompt(self, workflow: dict, client_id: str) -> str`
Submits a workflow to the ComfyUI prompt queue and returns the prompt ID.

##### Parameters
- **workflow** (dict) - The ComfyUI workflow definition.
- **client_id** (str) - A unique identifier for the client.

##### Returns
- **str**: The ID of the queued prompt.

#### `wait_for_completion(self, prompt_id: str, ws: websocket.WebSocket, timeout: float = None) -> dict`
Waits for a specific prompt to complete execution, using a WebSocket connection for real-time updates.

##### Parameters
- **prompt_id** (str) - The ID of the prompt to wait for.
- **ws** (websocket.WebSocket) - An active WebSocket connection.
- **timeout** (float, optional) - Maximum time to wait for completion.

##### Returns
- **dict**: The job details from the ComfyUI history.

##### Raises
- **TimeoutError**: If the job does not complete within the specified timeout.
- **RuntimeError**: If the job is missing from history or encounters an error.

#### `get_history(self, prompt_id: str) -> dict`
Retrieves the execution history for a given prompt ID.

#### `get_queue(self) -> dict`
Fetches the current state of the ComfyUI prompt queue.

#### `interrupt(self) -> None`
Sends an interrupt signal to stop the currently executing prompt.

#### `clear_queue(self) -> None`
Clears all pending jobs from the ComfyUI prompt queue.
```

--------------------------------

### LLM-driven prompting pipeline overview

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Illustrates the flow of data and processing steps in the LLM-driven prompting pipeline for video generation. It shows how raw scene descriptions are processed by an LLM to generate unique prompts for each image.

```text
JoyCaption -> captions.txt (raw scene descriptions, never modified)
      |
      v
LLM reads captions.txt + prompting-guides/ltx-2.3-prompting-guide.md
      |
      v
ltx_video_prompts.json (versioned, unique prompt per image)
      |
      v
Batch runner loads JSON -> queues to ComfyUI
```

--------------------------------

### Texture and Material Prompting for LTX 2.3

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Describe specific textures, materials, and fine details to take advantage of LTX 2.3's improved latent space and VAE for sharper detail.

```text
Close-up of wind moving through fine, curly hair. Individual strands visible.
Soft afternoon backlight catching edge detail.
```

--------------------------------

### Batch run starter script

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

A sanitized Python script designed to initiate batch operations. This script serves as a template for running multiple tasks or workflows in a controlled manner.

```python
scripts/template_run_batch.py
```

--------------------------------

### Recommended Prompt Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/wan-2.2-prompting-guide.md

Follow this order for effective video generation prompts: Subject, setting, action/motion, camera, mood/lighting, and temporal progression.

```text
Subject -> setting -> action/motion -> camera -> mood/lighting -> temporal progression
```

--------------------------------

### Recommended Batch Job Pattern in Python

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/batch-operations.md

This pattern demonstrates the recommended approach for running batch jobs. It involves establishing a single WebSocket connection and client ID for the entire batch, iterating through jobs, building workflows, queuing prompts, blocking until each job is complete using the WebSocket, and finally verifying the results with the history endpoint. Ensure to close the WebSocket connection upon completion or error.

```python
import uuid, json, requests, websocket

client_id = str(uuid.uuid4())
ws = websocket.WebSocket()
ws.connect(f"ws://{host}/ws?clientId={client_id}")

try:
    for job in jobs:
        workflow = build_workflow(job)           # patch only what changes
        prompt_id = queue_prompt(workflow, client_id)
        wait_for_completion(prompt_id, ws)       # block until done
        verify_with_history(prompt_id)            # confirm outputs exist
finally:
    ws.close()
```

--------------------------------

### Interrupt Running Job

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/api.md

Stop a currently running ComfyUI job if supported by the installation.

```APIDOC
## POST /interrupt

### Description
Stop a running job when supported by the ComfyUI installation.

### Method
POST

### Endpoint
/interrupt
```

--------------------------------

### Running JoyCaption with llama.cpp's mtmd CLI

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

This command demonstrates how to run JoyCaption using llama.cpp's mtmd CLI. Ensure you substitute your specific model, mmproj, and image paths. The output is redirected to `captions.txt`.

```bash
# Example for llama.cpp's mtmd CLI. Substitute your own binary and flags.
llama-mtmd-cli \
  --model /path/to/joycaption/model.gguf \
  --mmproj /path/to/joycaption/mmproj.gguf \
  --image path/to/image.jpg \
  --prompt "Write a long, detailed caption." \
  > captions.txt
```

--------------------------------

### Motion Prompting with Verbs for I2V

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Use strong verbs to clearly define motion and camera actions for image-to-video (I2V) generation in LTX 2.3, avoiding vague descriptions.

```text
Avoid:       The scene comes alive
Try:         The camera slowly pushes forward as the subject turns their head
             and begins walking toward the street. Cars pass.
```

--------------------------------

### Build FLUX Text-to-Image Workflow

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Creates a patched deep copy of the base FLUX 2 image-gen (T2I) workflow. Overrides only the text prompt.

```python
def build_flux_t2i_workflow(prompt: str, base_workflow_path: str) -> dict:
    """
    Returns a fully patched deep copy of the base FLUX 2 image-gen (T2I) workflow.
    Override: text prompt only (node 135). Output is whatever the workflow's
    SaveImage node writes -- usually ComfyUI's `output/Flux2_Klein_9b_kv/`.
    """
    wf = copy.deepcopy(load_workflow(base_workflow_path))
    wf["135"]["inputs"]["text"] = prompt
    return wf
```

--------------------------------

### Targeted Negative Prompt Example

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Keep negative prompts brief and focused on specific undesirable elements. Avoid listing synonyms; let the positive prompt define desired outcomes.

```text
Negative: "avoid locked-off static frame as sole camera behaviour, frozen motion, still photography, cartoonish"
```

--------------------------------

### Avoiding Static Prompts for LTX 2.3

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Ensure prompts describe action and movement rather than static scenes to prevent LTX 2.3 from generating photo-like, non-dynamic output.

```text
Instead of:  A dramatic portrait of a man standing
Try:         A man stands on a windy rooftop. His coat flaps in the wind.
             He adjusts his collar and steps forward as the camera tracks right.
```

--------------------------------

### ComfyUI Agent Toolkit Workflow Execution

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

This Python script demonstrates a full workflow for an agent interacting with ComfyUI. It includes steps for checking ComfyUI's availability, loading a workflow, modifying its inputs (prompt, image source, output path), and queuing the prompt for execution. It also shows how to wait for the job to complete and verify the output.

```python
# 1. Discover the install
from api_lib import comfyui_is_alive, get_object_info
assert comfyui_is_alive("http://127.0.0.1:8188")
nodes = get_object_info("http://127.0.0.1:8188")
assert "Flux 2 Image edit workflow API.json" or equivalent exists  # confirmed via object_info

# 2. Load + patch the base workflow
from api_lib import load_workflow
import copy
wf = copy.deepcopy(load_workflow("workflows/flux_2_i2i.json"))
wf["6"]["inputs"]["text"]    = "moody cyberpunk cinematic, neon rim light, volumetric fog"
vf["198"]["inputs"]["image"] = copy_to_comfyui_input("D:/renders/sci-fi/shot_001.png")
vf["225"]["inputs"]["output_path"] = "D:/renders/sci-fi/cinematic/batch_01"

# 3. Queue, block on completion, verify with /history
from api_lib import queue_prompt, wait_for_completion
import uuid, websocket
client_id = str(uuid.uuid4())
ws = websocket.WebSocket()
ws.connect(f"ws://127.0.0.1:8188/ws?clientId={client_id}")
prompt_id = queue_prompt(wf, host="http://127.0.0.1:8188", client_id=client_id)
job = wait_for_completion(prompt_id, ws=ws, host="http://127.0.0.1:8188")
# -> "OK: shot_001.png"  (only after the server confirms success, not just submission)
```

--------------------------------

### ComfyUI Workflow File Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/demo-workflows/README.md

Illustrates the directory structure for the provided demo workflow files. These files serve as the source of truth for node maps.

```text
demo-workflows/
├── Flux 2 Image edit workflow API/
│   └── Flux 2 Image edit workflow API.json
├── Flux 2 image gen/
│   └── Flux 2 image gen.json
└── ltx 2.3/
    ├── LTX 2.3 Video I2V_T2V_ZAM.json
    ├── LTX 2.3 Video I2V_T2V_Quality.json
    └── LTX 2.3 Prompting Guide.txt
```

--------------------------------

### LoRA training pipeline overview

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Describes the stages involved in the LoRA training pipeline, from dataset preparation and dynamic prompting to checkpoint management and deployment to ComfyUI.

```text
Dataset prep -> JoyCaption-assisted descriptions -> dynamic prompting variants
      |
      v
Training config + run -> checkpoint management
      |
      v
Deploy selected checkpoint to ComfyUI
```

--------------------------------

### Specific Prompting for LTX 2.3

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Use detailed descriptions for subjects, environment, lighting, and actions to improve prompt interpretation by LTX 2.3.

```text
Instead of:  A woman in a café
Try:         A woman in her 30s sits by the window of a small Parisian café.
             Rain runs down the glass behind her. Warm tungsten interior lighting.
             She slowly stirs her coffee while glancing at her phone.
             Background softly out of focus.
```

--------------------------------

### Prompt Generation Pipeline

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

Illustrates the flow from JoyCaption descriptions to LLM-generated cinematic prompts and their subsequent use in ComfyUI.

```text
joycaption.md descriptions
        |
        v
LLM reads each ## filename section
        |
        v
LLM writes a UNIQUE cinematic prompt per image
(varied camera language, motion, mood -- NOT just scene description)
        |
        v
Prompts saved to {job_folder}/{model}_prompts.json
        |
        v
batch runner loads JSON -> ComfyUI
```

--------------------------------

### Build LTX Video Workflow

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Generates a patched deep copy of the base LTX video workflow. Overrides prompt text, source image, output path, and I2V/T2V mode.

```python
def build_ltx_workflow(filename: str, prompt: str, filename_prefix: str,
                       t2v_mode: bool = False,
                       base_workflow_path: str = None) -> dict:
    """
    Returns a fully patched deep copy of the base LTX video workflow.
    Overrides: prompt text, source image, output path, I2V/T2V switch.
    """
    wf = copy.deepcopy(load_workflow(base_workflow_path))

    wf["267:266"]["inputs"]["value"]          = prompt           # Prompt text
    wf["269"]["inputs"]["image"]             = filename         # Source image filename
    wf["75"]["inputs"]["filename_prefix"]    = filename_prefix # Output path + stem
    wf["267:201"]["inputs"]["value"]          = t2v_mode        # False=I2V, True=T2V

    return wf
```

--------------------------------

### Dated Job Folder Structure for Production

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/batch-operations.md

This recommended production layout groups runs by project and uses a date prefix to prevent overwrites. It is ideal for organizing multiple batch runs over time for a single project.

```text
{project_root}/jobs/
    {PROJECT_NAME}/
        {YYYY-MM-DD}_{short_description}/
            run_{PROJECT}_{BATCH}.py
            job_state.json
            batch_config.json

```

--------------------------------

### Build Hunyuan T2V Workflow

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Creates a deep copy of a Hunyuan T2V workflow, patching the prompt, negative prompt, output filename prefix, and frame rate. Node IDs are placeholders and should be confirmed.

```python
def build_hunyuan_t2v_workflow(
    prompt: str,
    negative_prompt: str,
    filename_prefix: str,
    frame_rate: int = 24,
    base_workflow_path: str = "",
) -> dict:
    """
    Returns a deep copy of a Hunyuan T2V workflow with the prompt,
    negative prompt, output filename prefix, and frame rate patched.
    Node IDs below are placeholders -- confirm from /object_info on the
    target install.
    """
    wf = copy.deepcopy(load_workflow(base_workflow_path))

    # Positive prompt
    wf["<CLIPTextEncode.pos>"]["inputs"]["text"] = prompt
    # Negative prompt
    wf["<CLIPTextEncode.neg>"]["inputs"]["text"] = negative_prompt
    # Output: filename_prefix and frame rate
    wf["<VHS_VideoCombine>"]["inputs"]["filename_prefix"] = filename_prefix
    wf["<VHS_VideoCombine>"]["inputs"]["frame_rate"]      = frame_rate

    return wf
```

--------------------------------

### Prompt Structure Skeleton

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/flux-2-prompting-guide.md

Use this skeleton to build prompts by filling in the bracketed sections for subject, context, composition, lighting, and style.

```text
[A clear subject and action], in [location/context], framed as [shot/composition],
with [lighting/color cues], rendered in [style/material detail].
```

--------------------------------

### ComfyUI Job Execution Flow

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Illustrates the step-by-step process for handling jobs in ComfyUI, from loading and patching workflows to queuing, monitoring, and result verification. This pattern ensures consistent and reliable job processing.

```text
load workflow (once) -> deep copy -> patch 3-5 nodes
        |
        v
queue via POST /prompt
        |
        v
BLOCK on WebSocket until ComfyUI says done
        |
        v
VERIFY with GET /history/{prompt_id}
        |
        v
record result -> next job (one persistent WS, one client_id, whole batch)
```

--------------------------------

### Native Portrait Composition for LTX 2.3

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Compose prompts intentionally for vertical video when generating portrait content with LTX 2.3, rather than cropping landscape.

```text
Don't treat vertical as cropped landscape. Frame for it.
Influencer vlogging while on holiday — shoot for vertical.
```

--------------------------------

### JSON Prompt Versioning Structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/reference-implementations.md

Use this JSON structure to save LLM-generated prompts with versioning information. Include a '_version' block detailing the version number, description, date, and negative prompt. Each image entry contains its specific prompt and description.

```json
{
  "_version": {
    "v": 1,
    "description": "Initial cinematic pass — outdoor scenes, warm lighting",
    "date": "2026-04-01",
    "negative": "avoid locked-off static frame as sole camera behaviour, frozen motion, still photography, cartoonish"
  },
  "image_001.jpg": {
    "prompt": "The camera slowly tracks right as the subject walks forward...",
    "description": "Person walking on cobblestone street at golden hour"
  }
}
```

--------------------------------

### Commercial Product Hero Prompt

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/prompting-guides/ltx-2.3-prompting-guide.md

Use this prompt for creating high-quality commercial visuals, focusing on product presentation with specific lighting and mood.

```text
Luxury skincare bottle on a wet stone surface, gentle push-in camera,
soft morning light, subtle water movement, premium beauty commercial mood,
minimal background distraction.
```

--------------------------------

### ComfyUI Agent Toolkit repository structure

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Provides a detailed breakdown of the ComfyUI Agent Toolkit's directory and file structure. This helps users navigate the project and locate specific configuration files, scripts, and documentation.

```text
comfyui-skill-public/
├── SKILL.md                       # Trigger scope + read path
├── AGENTS.md                      # AI agent cold-start instructions
├── README.md                      # You are here
├── setup.md                       # First-run / unknown install onboarding
├── api.md                         # REST + WebSocket API reference
├── workflow-patterns.md           # Programmatic graph building + validation
├── models.md                      # Family-specific loader / LoRA / training guidance
├── dependencies.md                # ComfyUI + Python packages + JoyCaption
├── batch-operations.md            # Queue-and-watch, state, recovery, intake questionnaire
├── reference-implementations.md   # Node maps (FLUX I2I, FLUX T2I, LTX, WAN, Hunyuan) + code patterns
├── cron-jobs.md                   # Scheduler-agnostic monitoring SOP
├── prompting-guides/
│   ├── README.md
│   ├── general-prompting-guide.md
│   ├── ltx-2.3-prompting-guide.md
│   ├── flux-2-prompting-guide.md
│   └── wan-2.2-prompting-guide.md
├── scripts/
│   ├── api_lib.py                 # Production ComfyUI API helper (persistent WS, reconnect, env-var config)
│   └── template_run_batch.py      # Sanitized batch-run starter script
├── docs/
│   ├── Banner_openclaw.png        # Hero banner (this README's top image)
│   └── joycaption-convention.md   # JoyCaption naming, format, and pipeline convention
├── demo-workflows/                # READ ONLY examples — replace with your own
│   ├── Flux 2 Image edit workflow API/
│   ├── Flux 2 image gen/
│   └── ltx 2.3/
├── changelog.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
└── LICENSE
```

--------------------------------

### JoyCaption File Naming Variants

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/docs/joycaption-convention.md

These are the possible naming conventions for JoyCaption files. Check all three to ensure no file exists.

```text
INPUT_FOLDER/joycaption.md
INPUT_FOLDER/joycaption_{foldername}.md
INPUT_FOLDER/joycaption_{asset_name}.md
```

--------------------------------

### Verify Input Folder for Image Files

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/AGENTS.md

Confirms that the input folder contains at least one image file, which is necessary for image-to-image or image-to-video operations.

```python
Input folder has at least one image file (for I2I / I2V).
```

--------------------------------

### Check for Existing Cron Monitor

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/cron-jobs.md

Lists existing cron jobs or timers to check if a monitor is already set up. Use `grep` to filter for ComfyUI-related jobs.

```bash
# OpenClaw example
openclaw cron list
```

```bash
# Linux cron
crontab -l | grep -i comfy
```

```bash
# systemd
systemctl --user list-timers
```

--------------------------------

### ComfyUI Architecture Layers

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/README.md

Describes the two primary layers of the ComfyUI Agent Toolkit: the comfy-cli for managing the server lifecycle and custom nodes, and the REST + WebSocket API for workflow execution, parameter injection, and monitoring.

```text
+---------------------------------------------------------------+
|  Layer 1: comfy-cli (official lifecycle tool)                 |
|    Setup, server lifecycle, custom nodes, models              |
|    -> comfy install / launch / stop / node / model            |
+-----------------------------+---------------------------------+
                              |
+-----------------------------v---------------------------------+
|  Layer 2: REST + WebSocket API + skill scripts                |
|    Workflow execution, param injection, monitoring, downloads |
|    -> POST /api/prompt, GET /api/view, WS /ws                 |
|    -> scripts/api_lib.py, scripts/template_run_batch.py        |
+---------------------------------------------------------------+
```

--------------------------------

### Python Batch Script Invocation

Source: https://github.com/zambav/comfyui-agent-toolkit/blob/main/batch-operations.md

Use the appropriate Python launcher to run batch scripts. Verify the ComfyUI input directory path matches the target machine before running.

```bash
# Windows (if python not in PATH)
py -3 run_batch.py
```

```bash
# Linux/macOS
python3 run_batch.py
```
Tokens:
Raw