zipic
/zipic
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 integrati
- Author
- okooo5km ↗
- Repository
- skills4u ↗
- Licence
- MIT
- Last repository change
- 16.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/detect.ps1, scripts/detect.sh
What it does and when to use it
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 integrati
Triggers from the description
Original author 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 integrati
How it works
- Platform and shell
- Compress
- When the CLI fails
- Fallback: URL Scheme
- SVG and presets quick notes
- Zipic-usage questions
SKILL.md preview
---
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
```text
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`.
```bash
# 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
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](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](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
- **PDF** (Pro): a PDF is compressed as a PDF by default. `--pdf-to-image` with a target `--format` exports every page instead (`report-p01.webp`…, single page `report.webp`), all-or-nothing, one result row per page with `saved_pct` 0 — report page count and sizes, not savings. Use `--dry-run` first for `data.plan.pdf_pages` on big PDFs. Details: `reference/cli.md` → PDF to images.
- **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.
Files in this package (10)
- CHANGELOG.md 17 KB
- LICENSE 1 KB
- SKILL.md 10 KB
- evals/evals.json 17 KB
- reference/cli.md 34 KB
- reference/resources.md 5 KB
- reference/url-scheme.md 8 KB
- reference/windows.md 12 KB
- scripts/detect.ps1 3 KB
- scripts/detect.sh 3 KB
Versions
The database has no other skills named zipic.
Database snapshot: 13.11.2026 · package version 44c91ebf2867 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 98image-compress-automation
Use when compressing, resizing, or converting bulk product images (PNG, JPG, WEBP, AVIF) to web-ready JPG, WebP, or AVIF files in this repository, setting up a user's working folder on a new machine, or troubleshooting height-only sizing, aspect-ratio errors, and CLI flags. - 100web-ready
Use when the user wants to take a folder of images (any mix of HEIC, RAW, PNG, JPEG, TIFF, WebP) and produce a web-ready set — EXIF stripped, resized to a sensible max dimension, encoded in modern formats (AVIF + WebP, with JPEG fallback), and optimised for size. End-to-end… - 100to-jxl
Convert images to JPEG XL format (.jxl) with quality presets (lossless, visually lossless, or web). Use when you want optimal compression for photo archival or long-term storage, especially from JPEG originals where lossless transcoding preserves the original bitstream at smaller file size. - 100image-compression
This skill should be used when the user asks to "compress an image", "optimize images", "reduce image file size", "make images smaller", "convert to WebP", "convert to AVIF", "optimize images for the web", "create a srcset", "responsive images", "compress a GIF", "shrink a GIF",… - 100image-batch
Batch process images for marketing. Use when: resizing images for social media; compressing images for web; removing backgrounds; adding watermarks; converting formats to WebP; optimizing for Core Web Vitals - 100seo-images
Image optimization analysis for SEO and performance. Checks alt text, file sizes, formats, responsive images, lazy loading, CLS prevention, image SERP rankings (via DataForSEO), and image file optimization (WebP/AVIF conversion, IPTC/XMP metadata injection). Use when user says…