imgcli

Use this skill to run imgcli for agent-native image processing tasks: image inspection, normalization and format conversion, fixed-layout card composition, recipe-driven workflow execution, multi-platform variant export, smart padding to platform presets, packaging images into PDFs with visible text watermarks, and vertically stitching images into long composites with machine-readable JSON output.

install

source · Clone the upstream repo

git clone https://github.com/geekjourneyx/imgcli

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/geekjourneyx/imgcli "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/imgcli" ~/.claude/skills/geekjourneyx-imgcli-imgcli && rm -rf "$T"

manifest: skills/imgcli/SKILL.md

source content

imgcli

用于指导 Agent 直接执行

imgcli

，而不是解释底层图像算法实现。

项目边界

```
imgcli
```
不负责生成图片。
图片生成应由外部工具完成，例如 Gemini、GPT Image 或其他 provider CLI/API。
```
imgcli
```
负责对已经存在的图片做检查、加工、排版、打包和导出。

执行前检查

先检查是否已构建：
```
imgcli version
```
或
```
./bin/imgcli version
```
如果未安装但仓库存在，优先执行：

make build
./bin/imgcli version

默认使用 JSON 输出，不要关闭
```
--json
```
输入路径必须存在；输出扩展名必须与目标格式匹配

常用工作流

Inspect

./bin/imgcli inspect \
  --input input.jpg \
  --hash \
  --color-stats

可选：

```
--input-dir ./images
```
```
--limit 10
```

Compose

./bin/imgcli compose \
  --input input.jpg \
  --output poster.jpg \
  --width 1080 \
  --height 1440 \
  --layout poster \
  --title "Launch Day" \
  --subtitle "A fixed-layout creator card"

可选：

```
--logo brand.png
```
```
--badge NEW
```
```
--background-color '#f3efe7'
```
```
--safe-area 64,64,64,64
```

Convert

./bin/imgcli convert \
  --input alpha.png \
  --output out.jpg \
  --flatten-background "#ffffff" \
  --max-width 1600 \
  --quality 82 \
  --strip-metadata

Run

./bin/imgcli run \
  --recipe recipe.json \
  --dry-run
./bin/imgcli run \
  --recipe recipe.json

引用规则：

```
input:<name>
```
引用顶层输入
```
step:<id>
```
引用前置 step 产出的文件

Variants

./bin/imgcli variants \
  --input poster.jpg \
  --output-dir dist \
  --preset-set creator-basic

可选：

--preset xiaohongshu --preset wechat_cover

```
--background blur|solid
```

--filename-template '{base}_{preset}{ext}'

SmartPad

./bin/imgcli smartpad \
  --input input.jpg \
  --output output.jpg \
  --preset xiaohongshu

可选：

```
--background blur|solid
```
```
--blur-sigma 5
```
```
--quality 85
```

Images to PDF

./bin/imgcli topdf \
  --input page1.jpg \
  --input page2.jpg \
  --output bundle.pdf \
  --watermark-text "internal" \
  --watermark-position tile

可选：

```
--input-dir ./images
```
```
--watermark-opacity 0.25
```
```
--watermark-size 42
```

Vertical Stitch

./bin/imgcli stitch \
  --input a.jpg \
  --input b.jpg \
  --output stitched.jpg \
  --width 1080

可选：

```
--input-dir ./images
```
```
--part-height-limit 65535
```
```
--quality 85
```

真实烟测

如果本机已经配置

baoyu-image-gen

，执行：

make real-smoke

该流程会：

生成 3 张真实测试图
跑通
```
inspect
```
跑通
```
compose
```
跑通
```
convert
```
跑通
```
variants
```
跑通
```
run
```
跑通
```
smartpad
```
、
```
topdf
```
、
```
stitch
```
校验输出文件类型并打印产物目录

输出契约

成功：

{"ok":true,"command":"smartpad","data":{}}

失败：

{"error":"reason","code":"INVALID_ARGUMENT","exit_code":2}

失败时最小处理

```
PRESET_NOT_FOUND
```
：检查
```
--preset
```
```
INVALID_ARGUMENT
```
：检查必填 flag 与输入模式冲突
```
CONFIG_ERROR
```
：检查
```
--recipe
```
文件扩展名和 JSON/YAML 语法
```
PLAN_INVALID
```
：检查 step 引用、重复 step id、必填字段
```
OUTPUT_CONFLICT
```
：检查 recipe 是否把多个 step 写到同一路径，或覆盖顶层输入
```
DECODE_FAILED
```
：检查图片是否损坏或格式不支持
```
PDF_WRITE_FAILED
```
：检查输出路径是否可写
```
CANVAS_TOO_LARGE
```
：减小
```
--width
```
或调低分卷阈值