---

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), 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.4.3 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 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)

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 (Pro; gated): when the user names a target size, use --max-size <size> instead of guessing levels. Units are 1000-based (500KB, 1.5MB, bare number = bytes; 1KB–10GB). Zipic picks the highest quality that fits (--level is the ceiling) and, if the lowest quality is still too big, scales the image down; add --keep-dimensions when pixel size must not change. Every capped row carries max_size_met; a miss is still state: "success" with exit 0, so check the field on each row and report misses and any dimension change. Details: reference/cli.md → Max file size.

Exit codes: 0 request completed / 1 runtime — read error.code from JSON / 64 bad args (may be stderr only) / 65 GUI unavailable after auto-launch. pro_required returns upgrade/trial context in error.data (purchase_url, trial_available when present) — surface it, don't bypass. Format gates vary by platform; Windows uses ICO rather than macOS ICNS. Per-file quota/failure states must also be reported.

For preset / history / dry-run / pro_required schema: reference/cli.md.

When the CLI fails

On macOS, if zipic isn't on $PATH, or exit 65 persists after one retry, run from the skill directory:

bash scripts/detect.sh

Read the route field:

route	Action
cli	Re-run the CLI; it auto-launches Zipic and waits for the socket (how long depends on the CLI: reference/cli.md → Versions).
install_cli	CLI binary missing — tell user: Zipic menu bar → "Install zipic CLI". Use Fallback below for now.
url_scheme	Zipic < 1.9.5, no CLI exists — tell user to upgrade. Use Fallback below.
halt_no_app	Zipic not installed — suggest brew install --cask zipic or https://zipic.app.
halt_not_macos	This Bash detector is macOS-only. On Windows switch to scripts/detect.ps1; on WSL read the Windows reference.

On Windows, use the detection routes in reference/windows.md. There is no separate CLI installer: check the app execution alias and $env:LOCALAPPDATA\Microsoft\WindowsApps before reinstalling. The CLI auto-launches the packaged GUI and waits for its pipe; a cold start can time out with exit 65 while the GUI still comes up, so retry once. On persistent exit 65, open Zipic in the same user's desktop session and retry once. Do not repeatedly retry failed compression batches or run the GUI's executable as a CLI.

Fallback: URL Scheme

On macOS, use only when route is install_cli or url_scheme; on Windows, repair the alias first and use a URL only if CLI recovery is unavailable. URL Scheme has no result JSON or compression exit code. Load reference/url-scheme.md before constructing the URL: parameter names and semantics differ by platform (ratio is particularly different). Percent-encode paths, use a separate output directory and inspect actual files afterward. Launching the URL does not prove compression succeeded.

SVG and presets quick notes

• SVG optimization (Pro; macOS Zipic ≥ 1.9.0, also supported on Windows): pass .svg files like any other input. Output stays SVG — never set --format on SVG. Level 1–2 conservative, 3–4 balanced, 5–6 may simplify paths visibly.
• Presets (CLI only): zipic preset list --json, zipic preset show "<name>" --json, zipic preset create --name "Web 2x" --level 3 --format webp --width 2400. zipic preset set-default "<name>" selects the active preset — the baseline a flag-less compress inherits. Free users may keep at most 1 custom preset.
• History (CLI only): zipic list --json --limit 20 / zipic list clear.

Zipic-usage questions

For pricing, Pro features, troubleshooting, activation, comparisons, etc. — load reference/resources.md. It indexes https://zipic.app, https://docs.zipic.app, the AI-friendly index at https://zipic.app/llms.txt, and per-topic deep links (incl. Chinese mirrors). Fetch the canonical page; don't guess.