Metadata-Version: 2.4
Name: comfyui-agent-skill-mie
Version: 0.1.5
Summary: ComfyUI workflow execution skill for agents with packaged workflows and CLI tooling
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/MieMieeeee/comfyui-agent-skill
Project-URL: Repository, https://github.com/MieMieeeee/comfyui-agent-skill
Project-URL: Issues, https://github.com/MieMieeeee/comfyui-agent-skill/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: websockets
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# ComfyUI Agent Skill

This repository is an Agent Skill folder (Claude Code / Claude.ai / Agent Skills). The only required file is [SKILL.md](SKILL.md).

- 中文文档: [README.zh-CN.md](README.zh-CN.md)

## Status

- Stable interface: registered workflows only + CLI with structured JSON output.
- PyPI package: `comfyui-agent-skill-mie` (includes `comfyui-skill` alias).

## Install

This package is a local/self-hosted client for registered ComfyUI workflows.

- It **requires a local or trusted self-hosted ComfyUI server**
- It is **not** a hosted generation service
- It **does not** install ComfyUI itself

### Recommended: install with pipx

```bash
pipx install comfyui-agent-skill-mie
```

### Alternative: install with uv tool

```bash
uv tool install comfyui-agent-skill-mie
```

### Development / maintainer mode (source checkout)

```bash
git clone https://github.com/MieMieeeee/comfyui-agent-skill.git
cd comfyui-agent-skill
uv sync
uv run --no-sync python -m comfyui check
```

## Commands

### Recommended command

After installation, use the main command:

```bash
comfyui-agent-skill-mie check
comfyui-agent-skill-mie generate -p "a cute cat sitting on a windowsill at golden hour"
```

### Short alias

A shorter compatibility alias is also available:

```bash
comfyui-skill check
comfyui-skill generate -p "a cute cat sitting on a windowsill at golden hour"
```

## Upgrade

### pipx

```bash
pipx upgrade comfyui-agent-skill-mie
```

### uv tool

```bash
uv tool upgrade comfyui-agent-skill-mie
```

## Default server URL and networking notes

Default local examples use:

```text
http://127.0.0.1:8188
```

This is the most predictable default when the CLI/agent and ComfyUI run in the **same environment**.

If the agent runs inside **WSL, a container, or another sandbox** while ComfyUI runs on the **host OS**, `127.0.0.1` may refer to the runtime itself rather than the host machine. In that case, try one of the following:

```bash
comfyui-agent-skill-mie check --server http://localhost:8188
comfyui-agent-skill-mie check --server http://<host-ip>:8188
```

If you want to persist a non-default server URL:

```bash
comfyui-agent-skill-mie save-server http://localhost:8188
```

In tool-install mode, workflows and references are read from the installed package, while writable data goes to a per-user directory:

- Windows: `%APPDATA%\comfyui-skill`
- macOS: `~/Library/Application Support/comfyui-skill`
- Linux: `$XDG_DATA_HOME/comfyui-skill` or `~/.local/share/comfyui-skill`

## Registered Workflows

Stable (reviewed configs in `assets/workflows/*.config.json`):

- `z_image_turbo` (text-to-image)
- `klein_edit` (image edit)
- `qwen3_tts` (text-to-speech)
- `ltx-23-t2v` (text-to-video)
- `ltx-23-i2v` (image-to-video)
- `ace_step_15_music` (music/audio)
- `qwen_image_2512_4step` (text-to-image, excels at posters and images with embedded text)

Source of truth: the runtime registry is derived from `assets/workflows/*.config.json` (and the corresponding `assets/workflows/*.json` workflow files). If this list drifts, trust the configs and `comfyui-agent-skill-mie generate --help` output.

## Examples

### Text to Image (`z_image_turbo`)

Prompt:
```
年轻女生撑着透明伞，坐在草地上，肖像构图，柔和自然光，细节清晰，写实摄影风格
```

![z_image_turbo output](assets/examples/z_image_turbo.png)

### Reference to Image (`z_image_turbo`)

Reference image:

![reference input](assets/input/person.png)

User input:
```
生成同款服装的人在咖啡厅吃小蛋糕的图
```

Enhanced prompt (Agent vision analyzes the reference and generates):
```
Photorealistic, ultra-detailed portrait of a young woman with a short messy dark brown bob, wearing a chunky oatmeal-colored ribbed-knit scarf and an oversized cardigan with bold horizontal stripes in navy blue, mustard yellow, and teal green. She is sitting at a cozy cafe table, eating a small cake with a fork, warm cafe interior with soft ambient lighting, relaxed and happy expression, shallow depth of field, 85mm f/2.0, cozy atmosphere
```

![reference_to_image output](assets/examples/reference_to_image.png)

### Text Poster (`qwen_image_2512_4step`)

Prompt:
```
A watercolor style poster. Centered large Chinese characters: 五一节快乐. Clean composition, soft colors, textured paper, high quality.
```

![qwen_image_2512_4step output](assets/examples/qwen_image_2512_4step.png)

### Image Edit (`klein_edit`)

Input:

![klein_edit input](assets/input/person.png)

Prompt:
```
只把人物的衣服换成连衣裙，保持脸部、发型、姿势、背景、光照与构图不变，真实自然
```

![klein_edit output](assets/examples/klein_edit.png)

### Text to Video (`ltx-23-t2v`)

Prompt:
```
一只猫懒洋洋地打哈欠，轻微镜头推近，柔和光线，真实自然运动，稳定画面
```

[ltx-23-t2v output (MP4)](assets/examples/ltx-23-t2v.mp4)

### Image to Video (`ltx-23-i2v`)

Input:

![ltx-23-i2v input](assets/input/person.png)

Prompt:
```
A cinematic close-up portrait of a young woman with a tousled chin-length bob, wearing a chunky-knit taupe scarf and an oversized striped cardigan. She gazes upward with a melancholic, contemplative expression, soft diffused twilight light illuminating her face from the upper left. Gentle breeze moves her hair. The camera slowly drifts laterally with subtle breathing motion. Shallow depth of field, atmospheric film grain, quiet and emotional mood.
```

[ltx-23-i2v output (MP4)](assets/examples/ltx-23-i2v.mp4)

### Text to Music (`ace_step_15_music`)

User input:
```
生成一段轻柔的钢琴氛围音乐
```

Enhanced prompt sent to workflow:
```
gentle piano ambient, soft warm pads, slow tempo, night writing mood, calm, quiet, slightly healing, minimal, smooth reverb
```

[ace_step_15_music output (MP3)](assets/examples/ace_step_15_music.mp3)

### Text to Speech (`qwen3_tts`)

User input:
```
生成御姐语音："谢谢你一直陪伴我到现在。"
```

CLI call:
```bash
comfyui-skill generate --workflow qwen3_tts --speech-text "谢谢你一直陪伴我到现在。" --instruct "模拟御姐角色：成熟自信、略带温柔，吐字清晰，语速适中，情绪真诚克制。"
```

[qwen3_tts output (MP3)](assets/examples/qwen3_tts.mp3)

## References

- [SKILL.md](SKILL.md) — primary entry for Agent usage
- [references/workflows.md](references/workflows.md) — workflow selection, sizing, and examples
- [references/cli.md](references/cli.md) — CLI contract, async jobs, output paths, JSON schemas, error codes
- [references/prompt_enhancement/](references/prompt_enhancement/) — prompt enhancement playbooks
- [references/workflow_nodes.md](references/workflow_nodes.md) — model and node requirements

## Troubleshooting

- Run an environment doctor check (server + workflow preflight):
  - `comfyui-skill doctor` (recommended)
  - `comfyui-agent-skill-mie doctor`
  - `uv run --no-sync python -m comfyui doctor` (source mode)
- If the agent/skill runs inside WSL/container/sandbox while ComfyUI runs on the host OS, `127.0.0.1` may point to the runtime itself instead of the host. Try `--server http://localhost:8188` or the host machine IP (and optionally persist it via `save-server`).
- `SERVER_UNAVAILABLE`: ComfyUI is not reachable at the target URL. Start ComfyUI or re-run with `--server http://<ip>:8188`.
- `PREFLIGHT_MISSING_NODES`: install/enable required custom nodes on the ComfyUI server.
- `PREFLIGHT_MISSING_MODELS`: download required model files on the ComfyUI server.
- `NO_OUTPUT`: workflow ran but no media could be retrieved; check the workflow output node and server logs/UI.
- For `PREFLIGHT_MISSING_NODES`, `PREFLIGHT_MISSING_MODELS`, or `NO_OUTPUT`, consult the dependency reference: [references/workflow_nodes.md](references/workflow_nodes.md).

## For Maintainers (Add / Review Workflows)

Maintenance docs are intentionally kept out of `SKILL.md` to keep the skill instructions user-focused.

- Maintainer entry: [MAINTAINER.md](MAINTAINER.md)
- Detailed workflow registration guide: [references/extension.md](references/extension.md)
