/zipic

name: zipic
description: |
  Local image compression and Zipic-app expert for macOS and native Windows. Uses the Zipic CLI with JSON results, per-file saved_pct and exit codes; URL Scheme is a limited fallback.
  Use for compressing, optimizing or shrinking images, batch compression, conversion to WebP/AVIF/HEIC/JXL (including lossless JPEG XL), exporting PDF pages as images, hitting a target file size ("under 500 KB", "max 2 MB"), SVG optimization, resizing, presets and compression history. Also use for Zipic pricing, Pro features, activation, free-tier limits, troubleshooting, comparisons, CLI setup and workflow integration.
  Requires the installed Zipic GUI in the same execution environment. Windows uses the packaged zipic.exe alias and PowerShell; macOS uses Zipic.app. Format support and integrations differ by platform.
license: MIT
compatibility: macOS with Zipic.app >= 1.9.5 for CLI (>= 1.9.0 for SVG via URL Scheme), or Windows 10 build 19041+ / Windows 11 with packaged Zipic and its zipic.exe execution alias. Windows examples support PowerShell 5.1 and 7. No native Linux CLI; WSL requires Windows interop and Windows-accessible paths.
metadata:
  version: 2.5.0
  author: 十里 & FRIDAY
  homepage: https://zipic.app
  changelog: ./CHANGELOG.md

Zipic

Image compression on macOS and Windows, 100% on-device. Drive the installed GUI via its CLI; URL Scheme is a fallback when the CLI is unavailable.

Platform and shell

Identify the OS, architecture and shell **where commands execute**, rather than the user's desktop OS. Keep the GUI, CLI and input/output paths on the same host and user account.

• **macOS**: use `zipic` and POSIX shell syntax. If missing, run `bash "<skill-dir>/scripts/detect.sh"`.
• **Native Windows**: read [reference/windows.md](reference/windows.md) before setup or compression. Use PowerShell and `zipic.exe`; run `& "<skill-dir>\scripts\detect.ps1"` to resolve the executable and verify its version. The packaged CLI is `ZipicCli.exe`, exposed as the `zipic.exe` app execution alias; the GUI's `Zipic.exe` is a different executable.
• **WSL**: there is no Linux Zipic binary. Use Windows PowerShell through WSL interop with paths converted by `wslpath -w`, following the Windows reference. A Linux container or remote Linux host without Windows interop cannot invoke the Windows GUI.

Resolve `<skill-dir>` from this loaded skill's location; script paths are not relative to the user's project. On Windows use `& $exe` for a resolved executable, `$env:NAME` for environment variables, quoted paths and argument arrays. Do not copy Bash continuations, `open`, `brew` or `/tmp` paths into PowerShell.

Compress

zipic compress --json [flags] <files-or-dirs>...

`--json` is required — parse stdout separately from stderr. Capture the process exit code immediately (`$LASTEXITCODE` in PowerShell), then inspect `isError` and every `data.results[].state`; exit 0 alone does not prove every file succeeded. Report per-file `output_bytes`, errors, and `saved_pct` for `success` rows only (it is not meaningful on other states). An empty `results` with exit 0 means nothing was processed — say so instead of reporting success; rows that are all `skipped` mean the same for those files. Pass directories directly; Zipic walks them recursively.

| Need | Flag | | -------------------------- | ---- | | Compression level (1–6) | `--level 3` (1 = best quality, 6 = smallest) | | Convert format | `--format webp` (also `jpeg\|png\|avif\|heic\|jxl`) | | Cap width | `--width 1920` (aspect kept by default) | | Custom output directory | `--output /tmp/out/` (auto-sets `--location custom`) | | Mirror source tree | `--keep-hierarchy` | | Use a saved preset | `--preset "Web 1x"` (explicit flags override) | | Keep sources on conversion | `--no-overwrite` (gated) or `--output <dir>` (any version) | | Preview without running | `--dry-run` | | Lossless JPEG XL | `--format jxl --jxl-lossless` (gated) | | Cap output file size | `--max-size 500KB` (Pro; gated) | | PDF pages to images | `--pdf-to-image --format webp` (Pro; gated; one row per page) |

**Gated flags**: before passing one, confirm the top-level `zipic --help` lists it. Older CLIs accept unknown flags silently — the flag is dropped or swallows the next argument, and the run still exits 0. Probe only with `zipic --help`, never `zipic compress --help` (on older CLIs that can run the compression). Which version added what lives in one place: `reference/cli.md` → Versions.

**Source-deletion warning**: flags you don't pass inherit from the user's *active preset*, and `overwrite` (GUI default ON) means a format conversion landing next to the source with the same base name **deletes the source file**. When the user didn't ask to replace sources: pass `--no-overwrite` (gated), or write to a separate `--output` dir — safe on every version. `--dry-run --json` echoes the effective value at `data.plan.option.overwrite`. If help doesn't list `--no-overwrite` there is no reliable off switch — use the `--output` route. Full contract: `reference/cli.md`.

# Convert + resize + custom output
zipic compress --json --level 3 --format webp --width 1920 --output /tmp/out/ /path/photo.png

# Batch a folder
zipic compress --json --format webp --output /tmp/out/ /path/folder

**Lossless JXL** (gated): lossless sources become pixel-exact JXL and JPEGs are reversibly transcoded; already-lossy sources (lossy JXL/WebP, HEIC, AVIF, JPEG-in-TIFF) come back as `state: "skipped"` with `skip_reason`, with no output and the source untouched. A `skipped` row without `skip_reason` is a different case (already optimized, see `reference/cli.md`). Report skips separately from failures; re-run only those inputs with `--no-jxl-lossless` if the user accepts lossy, warning them that this often grows the file. Details: `reference/cli.md` → JXL lossless mode.

**Size cap