Skip to main content
skill CX Codex

comfy-workflow-ui — Claude Code skill: what it does, how to install

comfy-workflow-ui is a Claude Code skill that inspects and repairs ComfyUI App Mode forms in LiteGraph workflow files. It spots broken node serialization and restores missing UI widgets.

MIT ★ 139 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-code
Open on GitHub

What comfy-workflow-ui does

The skill audits LiteGraph JSON files designed for the modern ComfyUI Vue frontend. It enforces mapping UI controls exclusively inside the root extra.linearData property rather than altering node runtime dictionaries.

Injecting a literal widgets key into a serialized node dictionary breaks the LiteGraph deserializer. When this happens, live IBaseWidget instances lose their type field, causing the frontend to render empty title bars without sliders, inputs, or textareas.

Diagnostics rely on a bundled Python verification script that parses workflow nodes and slot references. Running the audit requires Python 3 on the host machine.

What it helps with

  • detect illegal widget keys inside ComfyUI workflow JSON
  • restore missing form inputs and sliders in Linear Mode
  • map input widgets and output nodes in extra.linearData
  • verify slot bindings for LoadImage, LoadVideo, and LoadAudio

Example prompts for the agent

  • Audit profiles/workflow.json for illegal serialized widgets
  • Inspect exposed App Mode inputs and outputs in workflow.json
  • Fix missing input controls in my ComfyUI Linear Mode workflow

How to install comfy-workflow-ui

1Skills CLI (Vercel)

npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-code

2Manually: put the files in place

~/.claude/skills/comfy-workflow-ui/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/comfy-workflow-ui/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about comfy-workflow-ui

How to install comfy-workflow-ui in Claude Code?

Run npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-code in your terminal.

What does comfy-workflow-ui do?

It guides AI agents through validating and configuring LiteGraph JSON schemas for ComfyUI App Mode without breaking UI rendering.

What causes form inputs to disappear in ComfyUI App Mode?

Adding a widgets key directly to serialized node JSON overwrites live widget objects with untyped dictionaries during hydration.

Source text

SKILL.md · MIT
---
name: comfy-workflow-ui
description: Audit, inspect, debug, and configure ComfyUI App Mode (Linear Mode) and LiteGraph UI forms in Comfy Colab Kit workflows.
---

# ComfyUI Workflow UI & App Mode Maintenance Skill (`/comfy-workflow-ui`)

This skill guides AI agents and engineers in maintaining, inspecting, and debugging **ComfyUI App Mode (Linear Mode)** forms and LiteGraph workflow JSON specifications in Comfy Colab Kit.

---

## 1. When to Use This Skill

Activate this skill whenever:
- Adding or modifying a workflow in `profiles/` with App Mode support (`extra.linearMode = true`).
- App Mode forms render improperly (e.g., only titles appear without input boxes, textareas, sliders, or image upload buttons).
- Auditing workflow JSON cleanliness to ensure compatibility with ComfyUI's modern Vue frontend (`comfyui-frontend-package`).
- Customizing input titles, labels, default values, or media upload drop zones.

---

## 2. The Three Golden Invariants of Workflow UI

ComfyUI's frontend (`Comfy-Org/ComfyUI_frontend`) uses Vue 3 components (`AppModeWidgetList.vue`, `NodeWidgets.vue`, `WidgetGrid.vue`, `DropZone.vue`) mounted over a LiteGraph runtime canvas. To ensure form controls render correctly, you **MUST** uphold these three invariants:

### 🚨 Invariant 1: Top-level `extra.linearData` is the ONLY place for App Mode mapping
Never mutate node execution dictionaries to configure App Mode. All UI bindings are declared exclusively at the workflow root:

```json
{
  "extra": {
    "linearMode": true,
    "linearData": {
      "inputs": [
        [30, "image"],
        [6, "value"],
        [8, "text"],
        [20, "denoise"],
        [1, "choice"],
        [22, "value"],
        [23, "width"],
        [23, "height"]
      ],
      "outputs": [
        26
      ]
    }
  }
}
```

- Each entry in `inputs` is `[node_id, widget_name]` (or `[node_id, widget_name, { height, description }]`).
- Each entry in `outputs` is `node_id`.

### 🚨 Invariant 2: NEVER put a `"widgets"` key in a node dictionary
- **The Mechanism**: In the official `ISerialisedNode` spec, serialized node dictionaries have no `widgets` key; values live in `widgets_values: [...]`. At runtime, `node.widgets` contains live JavaScript class instances (`IBaseWidget`).
- **The Pitfall**: If Python code (such as `setup.py` or a preprocessing script) writes `node["widgets"] = [{"name": wname, "label": ...}]`, LiteGraph's deserializer (`hydrateExtensionPayload`) treats `widgets` as an unknown extension and runs `Object.assign(this, { widgets: [...] })`.
- **The Consequence**: This completely overwrites real widget instances with hollow dicts that lack `.type`. `processedWidgetRenderModel.ts` drops every widget whose `type` is undefined (`if (!type) return null`). Result: **Only title bars appear; all form inputs, textareas, and sliders vanish!**

### 🚨 Invariant 3: Widget labels round-trip through canonical backing slots
- **The Mechanism**: LiteGraph restores widget labels via backing input slots where `input.widget?.name === w.name`:
  ```typescript
  const input = this.inputs.find((i) => i.widget?.name === w.name);
  if (input?.label) w.label = input.label;
  ```
- **The Rule**: When assigning widget labels, ensure the slot in `node.inputs` carries:
  ```json
  {
    "name": wname,
    "type": slot_type,
    "widget": { "name": wname },
    "label": label,
    "link": null
  }
  ```
  App Mode (`AppModeWidgetList.vue`) displays `action.widget.label || action.widget.name`.
- **The Pitfall**: Never inject a bare slot without `"widget": {"name": wname}`. Without the inner `widget` dict, LiteGraph treats it as a standard disconnected wire socket instead of a widget binder.

---

## 3. UI Inspection & Verification Runbook

### A. Quick Workflow Cleanliness Audit
Run this script to verify that a workflow JSON does not contain illegal serialized `widgets` or corrupted input slots:

```bash
python3 -c "
import json, sys

path = sys.argv[1] if len(sys.argv) > 1 else 'profiles/examples/moss-image/workflows/matlowai_img2img.json'
with open(path) as f:
    d = json.load(f)

corrupted = []
for n in d.get('nodes', []):
    nid = n.get('id')
    if 'widgets' in n:
        corrupted.append(f'Node {nid} has illegal \"widgets\" key (breaks live widgets)')
    for slot in n.get('inputs', []):
        if slot.get('widget') is None and slot.get('name') in ['image', 'denoise', 'choice']:
            # verify it is a real connection slot or a legitimate converted widget
            pass

if corrupted:
    print('❌ FAILED: Found workflow UI corruption:')
    for err in corrupted:
        print('  -', err)
    sys.exit(1)
else:
    print('✅ PASSED: Workflow node structures are clean.')
" <path-to-workflow.json>
```

### B. Inspect App Mode Inputs in a Workflow
Check which node IDs and widget names are currently exposed in App Mode:

```bash
python3 -c "
import json, sys

path = sys.argv[1] if len(sys.argv) > 1 else 'profiles/examples/moss-image/workflows/matlowai_img2img.json'
with open(path) as f:
    d = json.load(f)

extra = d.get('extra', {})
print('linearMode:', extra.get('linearMode'))
ldata = extra.get('linearData', {})
print('App Inputs:')
nodes = {n['id']: n for n in d.get('nodes', [])}
for item in ldata.get('inputs', []):
    nid, wname = item[0], item[1]
    n = nodes.get(int(nid) if str(nid).isdigit() else nid)
    ntype = n.get('type') if n else 'MISSING NODE'
    title = n.get('title') if n else ''
    print(f'  Node {nid:2} [{ntype:25}] widget: {wname:12} title: {title}')
print('App Outputs:', ldata.get('outputs', []))
" <path-to-workflow.json>
```

### C. Native Media Loaders (`LoadImage`, `LoadVideo`, `LoadAudio`)
Native drop zones in App Mode are hardcoded in `getLoaderDropIndicator.ts`:
- `LoadImage`: expects widget name `"image"`.
- `LoadVideo`: expects widget name `"file"`.
- `LoadAudio`: expects widget name `"audio"`.

The upload button triggers `node.widgets.find(w => w.name === 'upload').callback()`. Ensure `LoadImage` nodes retain their standard widget structure.

---

## 4. Renaming & Label Best Practices

When friendly or localized field labels (e.g. `正向提示词 (Positive Prompt)`) are desired:

1. **Modify `node["title"]` (Recommended & Safest)**:
   In ComfyUI workflow JSON, `node.title` is a first-class canonical field. Setting `node["title"] = "正向提示词 (Positive Prompt)"` is safe, clean, and displays prominently in both Graph and App modes.

2. **Backing Input Slot Label**:
   For core nodes whose widgets are backed by an input slot (such as `CLIPTextEncode` where `input.widget.name == "text"`), set `input["label"] = "正向提示词"`. Never add a new slot if one doesn't exist.

3. **Never touch `node["widgets"]`**:
   Leave `node.widgets` entirely to the ComfyUI frontend runtime.

---

## 5. Troubleshooting Checklist

| Symptom | Root Cause | Fix |
|---|---|---|
| **Only titles appear, no inputs/sliders/textareas** | Node dictionaries have `widgets: [...]` in JSON, wiping out live `IBaseWidget` instances. | Remove `widgets` from node JSON dictionaries. Parameter values belong in `widgets_values`. |
| **Image node has no upload button or drop zone** | `node.widgets` was clobbered (breaking `upload` button) or `onDragDrop` failed to attach. | Keep node structure clean and map `[node_id, "image"]` in `linearData.inputs`. |
| **Widget row shows empty slot with dot instead of control** | Artificial slot injected into `node.inputs`, making frontend treat it as a converted connection. | Remove spurious input slots from `node.inputs`. |
| **App Mode toggle doesn't open on first load** | `extra.linearMode` is false or missing, or `default_view: "app"` not set in `profile.yaml`. | Set `extra.linearMode = true` and ensure profile specifies `default_view: app`. |

---

## 📚 Upstream Code References

The source of truth is the [Comfy-Org/ComfyUI_frontend](https://github.com/Comfy-Org/ComfyUI_frontend) repository:
- `src/renderer/extensions/linearMode/`: App Mode layout, controls (`LinearControls.vue`), and drop zones (`DropZone.vue`).
- `src/components/builder/AppModeWidgetList.vue`: Widget list container and label rendering.
- `src/renderer/extensions/vueNodes/composables/processedWidgetRenderModel.ts`: Widget resolution and `processWidget` pipeline.
- `src/lib/litegraph/src/extensionPersistence.ts`: LiteGraph deserializer (`hydrateExtensionPayload`).
- Repository Documentation: [`docs/APP_MODE.md`](../../docs/APP_MODE.md).

© FireTable · MIT · FireTable/comfy-colab-kit

Similar skills

All skills for AI and ML →

Project sponsors

Companies that keep this analytics open