home / skills / jimliu / baoyu-skills / baoyu-compress-image

baoyu-compress-image skill

needs review

This skill compresses images by auto-selecting the best tool to output WebP or PNG, reducing sizes while preserving quality.

npx playbooks add skill jimliu/baoyu-skills --skill baoyu-compress-image

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

4.5 KB

---
name: baoyu-compress-image
description: Compresses images to WebP (default) or PNG with automatic tool selection. Use when user asks to "compress image", "optimize image", "convert to webp", or reduce image file size.
---

# Image Compressor

Compresses images using best available tool (sips → cwebp → ImageMagick → Sharp).

## Script Directory

Scripts in `scripts/` subdirectory. Replace `${SKILL_DIR}` with this SKILL.md's directory path.

| Script | Purpose |
|--------|---------|
| `scripts/main.ts` | Image compression CLI |

## Preferences (EXTEND.md)

Use Bash to check EXTEND.md existence (priority order):

```bash
# Check project-level first
test -f .baoyu-skills/baoyu-compress-image/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md" && echo "user"
```

┌────────────────────────────────────────────────────────┬───────────────────┐
│                          Path                          │     Location      │
├────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-compress-image/EXTEND.md           │ Project directory │
├────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md     │ User home         │
└────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ Use defaults                                                              │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Default format | Default quality | Keep original preference

## Usage

```bash
npx -y bun ${SKILL_DIR}/scripts/main.ts <input> [options]
```

## Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `<input>` | | File or directory | Required |
| `--output` | `-o` | Output path | Same path, new ext |
| `--format` | `-f` | webp, png, jpeg | webp |
| `--quality` | `-q` | Quality 0-100 | 80 |
| `--keep` | `-k` | Keep original | false |
| `--recursive` | `-r` | Process subdirs | false |
| `--json` | | JSON output | false |

## Examples

```bash
# Single file → WebP (replaces original)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png

# Keep PNG format
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png -f png --keep

# Directory recursive
npx -y bun ${SKILL_DIR}/scripts/main.ts ./images/ -r -q 75

# JSON output
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png --json
```

**Output**:
```
image.png → image.webp (245KB → 89KB, 64% reduction)
```

## Extension Support

Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.

Overview

This skill compresses and converts images to WebP (default) or PNG/JPEG using the best available toolchain. It selects the optimal encoder automatically and preserves or replaces originals based on your options. Designed for batch and single-file workflows, it reports size and percentage reductions.

How this skill works

The CLI examines available tools (system sips, cwebp, ImageMagick, or a bundled Sharp fallback) and picks the most effective encoder. It accepts files or directories, can recurse subdirectories, and outputs converted files with new extensions or to a specified output path. Quality, format, and keep-original behavior are configurable and it can emit JSON summaries for automation.

When to use it

Reduce image file size for web delivery or storage.
Convert PNG/JPEG assets to WebP for improved performance.
Optimize large image directories before deployment or publishing.
Create smaller thumbnails or preview images while keeping originals optional.
Automate image optimization in build scripts or CI pipelines.

Best practices

Test quality settings on representative images before batch processing to find the right balance.
Use recursive mode only on vetted directories to avoid unintended conversions.
Enable --keep to preserve originals during initial runs; remove originals once satisfied.
Use --json for programmatic workflows and CI integration.
Set format explicitly when you must keep PNG or JPEG rather than WebP.

Example use cases

Compress a single image in place to WebP with default quality (80).
Batch-convert an images/ folder recursively at quality 75 for web deployment.
Produce PNG outputs while keeping originals: convert image.png -f png --keep.
Run the CLI from build scripts and consume its JSON output to report total bytes saved.
Optimize a media directory before upload to reduce storage and CDN costs.

FAQ

Which formats are supported as input and output?

Most common inputs (PNG, JPEG, TIFF, etc.) are supported. Outputs can be webp, png, or jpeg as selected with --format.

How do I preserve original files?

Use the --keep (or -k) flag to write converted files alongside originals rather than replacing them.

Can I control quality and recursive processing?

Yes. Use --quality (0–100) to set compression level and --recursive (or -r) to process subdirectories.