Image Compression ( compress-image)#

Compress or convert generated images for delivery, preview, and social upload. Optimize image size, convert to webp, or reduce file size after generation.

This skill uses the best available local toolchain and stays self-contained.

Step 0: First-Trigger Readiness Gate#

When this skill is triggered for the first time in a project or environment, run:

bash

npm run ensure-ready -- --project .

This checks whether at least one supported local compressor is available.

• If no compressor tool is available, tell the user compression needs one of sips, cwebp, or ImageMagick and offer to install one on the user's behalf.
• No API key or secret config is needed for this skill.
• After the tool is available, continue directly to compression without extra setup steps.

Script:

• scripts/main.ts

Use Cases#

• files are too large to share easily
• output needs to be converted to webp
• a lighter preview image is needed
• images should be optimized before social upload

Example Prompts#

• Compress my cover image to webp for social upload
• Optimize all images in the output directory to reduce file size
• Convert this PNG to a lighter webp format at quality 80

Important: at least one of cwebp, magick, or sips must be available locally.

Backend Preference#

Preferred order:

1. cwebp for WebP output
2. magick or convert for conversion and flexible processing
3. sips as a macOS-native fallback

See:

• references/tool-selection.md

CLI#

bash

${BUN_X} {baseDir}/scripts/main.ts <input> [options]

Options#

OptionDescription<input>input file or directory--output, -ooutput file or directory--format, -f``webp, png, or jpeg (default: webp)--quality, -qquality 0-100 (default: 80)--keep, -kkeep the original when the output extension matches the input--recursive, -rprocess directories recursively--jsonreturn JSON output

Common Examples#

Single image to WebP:

bash

${BUN_X} {baseDir}/scripts/main.ts input.png -f webp -q 80

Single image to JPEG:

bash

${BUN_X} {baseDir}/scripts/main.ts input.png -f jpeg -q 82

Recursive directory compression:

bash

${BUN_X} {baseDir}/scripts/main.ts ./images -r -f webp

JSON output:

bash

${BUN_X} {baseDir}/scripts/main.ts input.png --json

Workflow#

1. On first trigger, run the readiness gate and confirm a supported compressor exists.
2. Identify the input: a single image file or a directory of images.
3. Choose the target format ( webp, png, or jpeg) and quality level.
4. Run the CLI with the chosen options.
5. Verify the output exists and is smaller than the input.
6. If processing a directory, use --recursive to handle nested folders.

Output Convention#

Recommended behavior:

• keep the original image untouched
• write the compressed result under a new name
• store results in the same directory or in a compressed/ subdirectory

Example:

text

cover-image/topic-slug/
├── cover.png
└── compressed/
    └── cover.webp

Re-run Behavior#

• Re-compressing the same input produces a new output file (or overwrites an existing one at the same path).
• The original input is never modified unless --keep is used and the output extension matches the input.
• --recursive re-processes all matching files in the directory, including previously compressed ones.
• To avoid double-compression, point --output to a separate compressed/ subdirectory.

Definition of Done#

• The compressed output file exists and is smaller than the input.
• The original file is preserved (not overwritten) unless --keep is used with matching extensions.
• Output format matches the requested --format.
• --json mode produces a valid JSON summary with input size, output size, and compression ratio.

Onboarding Commands#

bash

npm run doctor -- --project .
npm run ensure-ready -- --project .
npm run setup -- --project .

setup does not write secrets because this skill has none; it simply confirms readiness and tells the user the next compression command to run.

Current Behavior#

• prefers cwebp -> magick / convert -> sips
• supports single files and directories
• supports recursive scanning
• supports JSON summaries
• does not delete the original just because the format changes; use --keep when the output extension matches the input
• webp output requires cwebp or ImageMagick; if only sips is available, prefer png or jpeg