comfy-workflow-ui — скилл для Claude Code: что делает и как установить
Скилл comfy-workflow-ui для Claude Code проверяет и настраивает формы App Mode и структуру JSON в воркфлоу ComfyUI. Находит ошибки сериализации и возвращает пропавшие поля ввода.
MIT ★ 139 обновлён 2026-11-12
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-codeЧто делает comfy-workflow-ui
Скилл проверяет спецификации LiteGraph JSON для интерфейса ComfyUI на Vue 3 и чинит разметку Linear Mode. Все привязки формы должны объявляться строго в корневом блоке extra.linearData, где перечислены пары идентификаторов узлов и имён виджетов.
Главная ошибка при генерации таких файлов скриптами — запись ключа widgets внутрь словаря узла. Десериализатор LiteGraph заменяет живые классы виджетов пустыми словарями без поля type, из-за чего интерфейс рендерит только заголовки без слайдеров и текстовых полей.
Для проверки структуры скилл запускает готовый Python-скрипт аудита узлов и входных слотов. Для работы нужен установленный Python 3.
Какие задачи решает
- найти скрытые ошибки в JSON-файлах воркфлоу ComfyUI
- починить исчезнувшие поля ввода и слайдеры в App Mode
- настроить список полей ввода в блоке
extra.linearData - проверить корректность слотов загрузки изображений и аудио
Примеры запросов агенту
- Проверь файл воркфлоу
profiles/workflow.jsonна ошибки сериализации виджетов - Выведи список полей ввода и вывода для App Mode из
workflow.json - Переименуй заголовок узла промпта в JSON воркфлоу ComfyUI без поломки интерфейса
Как установить comfy-workflow-ui
1Через Skills CLI (Vercel)
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-code2Вручную: положить файлы
~/.claude/skills/comfy-workflow-ui/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/comfy-workflow-ui/
1Через Skills CLI (Vercel)
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a codex2Вручную: положить файлы
.agents/skills/comfy-workflow-ui/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a cursor2Вручную: положить файлы
.cursor/skills/comfy-workflow-ui/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install FireTable/comfy-colab-kit skills/comfy-workflow-ui2Вручную: положить файлы
.github/skills/comfy-workflow-ui/SKILL.md1Через Skills CLI (Vercel)
npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a gemini-cli2Командой платформы
gemini skills install https://github.com/FireTable/comfy-colab-kit --path skills/comfy-workflow-uiВручную: положить файлы
.devin/skills/comfy-workflow-ui/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о comfy-workflow-ui
Как установить comfy-workflow-ui в Claude Code?
Выполните команду npx skills add FireTable/comfy-colab-kit --skill comfy-workflow-ui -a claude-code в терминале.
Что делает comfy-workflow-ui?
Инструктирует агента по правилам верстки интерфейса App Mode в ComfyUI, помогает составлять блок extra.linearData и валидировать JSON узлов.
Почему в App Mode отображаются только заголовки без полей?
Проблема возникает из-за ключа widgets внутри словаря узла, который затирает нативные экземпляры IBaseWidget в LiteGraph.
Исходный текст
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