image-compress-skill

ImageCompressSkill

The intelligent image optimization engine for AI Agents. Smart routing between PNG quantization and WebP compression.

1. Smart Strategy Overview

The optimal compression strategy depends on the input content type and the target use case.

Content Type	Primary Strategy	Toolchain	Target Format
Photographs	Lossy WebP	image -> libwebp	.webp
Graphics / Logos / UI	Optimized PNG	image -> imagequant -> oxipng	.png
Universal (Web)	WebP (High Compat)	image -> libwebp	.webp
Universal (Archive)	Optimized PNG	image -> oxipng (Lossless)	.png

Decision Logic:

1. Try WebP First (Default): For most web use cases, WebP offers the best size/quality ratio (30-90% reduction).
2. Fallback to PNG: If the input is a simple graphic (low color count) OR if WebP results in a larger file (rare, but happens with simple shapes), use the Quantized PNG pipeline.
3. Strict Quality: If the user demands "Lossless" or "No visual change", skip quantization and use only oxipng (PNG) or Lossless WebP.

Setup

This skill requires the image-compress-tool binary.

If the tool is not found, the agent should run:

./scripts/install.sh

Usage

1. Smart Compression (Auto)

Best for: Photos, complex gradients, web assets.

• Quality (-q):
  • 80-85: Sweet spot for web (visually indistinguishable). Default.
  • 75: Aggressive, might show slight artifacts on sharp edges.
  • 90+: Archival quality, diminishing returns.
• Method (-m):
  • 4: Default. Good balance.
  • 6: Slowest but best compression. Use for static assets (build time).
• Usage:

  // Rust (using webp crate)
  let encoder = webp::Encoder::from_image(&img)?;
  let memory = encoder.encode(80.0); // Q=80
  

B. Optimized PNG (via imagequant + oxipng)

Best for: Logos, icons, screenshots, line art, transparent assets.

• Step 1: Quantization (imagequant)
  • Quality: min=0, max=80 (or 80-90 for high fidelity).
  • Speed: 4 (Default). 1 (Slowest/Best).
  • Note: This step converts 32-bit RGBA to 8-bit Indexed Color. It is "lossy" but visually excellent for graphics.
• Step 2: Optimization (oxipng)
  • Level (-o):
    • 2: Default. Good balance.
    • 4: Recommended for production builds (slower but worth it).
    • 6: Max. Very slow.
  • Strip (--strip safe): Remove metadata.
  • Interlace (-i 0): Disable interlacing (saves ~20%).
• Usage:

  // Pipeline
  let (palette, pixels) = imagequant_attributes.quantize(img)?; // Step 1
  let png_data = encode_png(palette, pixels);
  let optimized = oxipng::optimize_from_memory(&png_data, &options)?; // Step 2
  

3. Implementation Rules for Agents

When implementing image compression tools:

1. Dual Mode Support: Always implement BOTH pipelines (WebP and PNG).
2. Smart Defaults:
   • Default Quality: 80 (for both WebP and ImageQuant).
   • Default WebP Method: 4.
   • Default Oxipng Level: 2 (or 4 if speed isn't critical).
3. Output Logic:
   • If user asks for "compress this image" -> Output WebP (smallest).
   • If user asks for "optimize this PNG" -> Output Quantized PNG.
   • If input is small (< 10KB) simple shape -> Check if WebP > PNG, if so, prefer PNG.

4. Code Resources

Dependency Setup

[dependencies]
image = "0.25"
imagequant = "4.4"
oxipng = "10.1"
webp = "0.3"
anyhow = "1.0"
clap = { version = "4.5", features = ["derive"] }

Rust Implementation Snippet (The "Golden Path")

See image-compress-tool/src/main.rs in the current project for the reference implementation that handles:

1. CLI Argument Parsing
2. Image Loading
3. WebP Branch (using webp crate)
4. PNG Branch (using imagequant -> png encoding -> oxipng)

5. Verification

Always verify:

1. File Size: Is output < input?
2. Format: Is it a valid WebP/PNG?
3. Visual: Open in browser/viewer.