baoyu-compress-image

Name: baoyu-compress-image
Author: Jim Liu

imagecompressionwebppngoptimizationperformanceassetscli

⭐ 21.7k🕒 2026-06-13Source ↗

Install this skill

npx skills add jimliu/baoyu-skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

The baoyu-compress-image skill provides a streamlined command-line interface for batch image optimization. It operates by identifying the most efficient available system compression tool—prioritizing native macOS sips, Google cwebp, or ImageMagick—and defaulting to the Sharp npm package if others are missing. The utility handles single-file and recursive directory processing, offering granular control over output format, quality levels, and file retention. By outputting both human-readable text logs and machine-parsable JSON, it integrates directly into automated build pipelines or CI/CD workflows. Users can perform format conversion or aggressive file size reduction while maintaining consistent visual fidelity, all triggered via simple Bun-based execution commands without requiring complex local software configurations or GUI-based editing tools.

When to Use This Skill

•Minimizing asset sizes for web front-end performance
•Batch-converting high-resolution PNG screenshots to WebP
•Automating image cleanup in project directories via CI scripts
•Reducing media footprints before uploading assets to cloud storage

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“Compress all images in the assets folder
“Convert this png to a webp file using the baoyu skill
“Run recursive optimization on the images directory
“What is the compression ratio of this image in JSON format?
“Reduce the file size of these screenshots to 75 quality

Pro Tips

💡Always test compressed images across different devices and browsers to ensure visual quality meets your standards, especially when adjusting the `--quality` parameter.
💡Utilize the `--recursive` (`-r`) flag when processing entire image directories to efficiently optimize all images in one command.
💡Leverage the `--format png` option when transparency is critical and the target environment requires PNGs, or when converting existing PNGs without changing their format.

What this skill does

•Supports recursive image directory processing
•Auto-selects optimal compression backend from system tools
•Generates structured JSON output for script integration
•Enables precise quality adjustments between 0 and 100
•Converts between common formats including WebP, PNG, and JPEG

When not to use it

✕When requiring non-lossy compression for print-ready assets
✕If your environment cannot run Bun or lacks Node.js support
✕For complex image editing tasks like cropping, resizing, or filtering

Example workflow

Identify the directory containing source images
Execute the main script via npx and Bun on the target folder
Specify the -r flag to enable recursive directory traversal
Set the -q quality parameter to balance size and fidelity
Pipe the output to a log file or JSON handler for audit
Verify file size reduction in the resulting console summary

Prerequisites

–Bun runtime environment installed
–Network access to fetch dependencies via npx

Pitfalls & limitations

!Requires system-level availability of sips, cwebp, or ImageMagick for best performance
!Default behavior overwrites files unless the --keep flag is provided
!Relies on external tool performance which varies by OS

FAQ

How does this tool decide which compressor to use?

It checks your system path in a specific priority order: macOS sips, cwebp, ImageMagick, and finally the Sharp npm package.

Can I keep my original images while compressing?

Yes, include the --keep flag in your command to preserve the source files while creating new compressed versions.

What happens if I specify a format that is not supported?

The script typically defaults to WebP or falls back to your specified format if the underlying compressor supports it.

Is the JSON output useful for shell scripts?

Yes, you can pipe the JSON output into tools like jq to extract specific data points such as compression ratio or file size.

How it compares

Unlike manual conversion or generic LLM-based image prompts, this skill offers deterministic, high-speed batch processing with verified system-level optimization backends.

Source & trust

⭐ 22k stars🕒 Updated 2026-06-13

View original skill on GitHub →

📄 Full skill instructions — original source: jimliu/baoyu-skills

# Image Compressor

Cross-platform image compression with WebP default output, PNG-to-PNG support, preferring system tools with Sharp fallback.

## Script Directory

**Important**: All scripts are located in the scripts/ subdirectory of this skill.

**Agent Execution Instructions**:
1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Script path = ${SKILL_DIR}/scripts/<script-name>.ts
3. Replace all ${SKILL_DIR} in this document with the actual path

**Script Reference**:
| Script | Purpose |
|--------|---------|
| scripts/main.ts | CLI entry point for image compression |

## Quick Start

# Compress to WebP (default)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png

# Keep original format (PNG → PNG)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png --format png

# Custom quality
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png -q 75

# Process directory
npx -y bun ${SKILL_DIR}/scripts/main.ts ./images/ -r

## Commands

### Single File Compression

# Basic (converts to WebP, replaces original)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png

# Custom output path
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png -o compressed.webp

# Keep original file
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png --keep

# Custom quality (0-100, default: 80)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png -q 75

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

### Directory Processing

# Process all images in directory
npx -y bun ${SKILL_DIR}/scripts/main.ts ./images/

# Recursive processing
npx -y bun ${SKILL_DIR}/scripts/main.ts ./images/ -r

# With custom quality
npx -y bun ${SKILL_DIR}/scripts/main.ts ./images/ -r -q 75

### Output Formats

# Plain text (default)
npx -y bun ${SKILL_DIR}/scripts/main.ts image.png

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

## Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| <input> | | Input file or directory | Required |
| --output <path> | -o | Output path | Same path, new extension |
| --format <fmt> | -f | webp, png, jpeg | webp |
| --quality <n> | -q | Quality 0-100 | 80 |
| --keep | -k | Keep original file | false |
| --recursive | -r | Process directories recursively | false |
| --json | | JSON output | false |
| --help | -h | Show help | |

## Compressor Selection

Priority order (auto-detected):

1. **sips** (macOS built-in, WebP support since macOS 11)
2. **cwebp** (Google's official WebP tool)
3. **ImageMagick** (convert command)
4. **Sharp** (npm package, auto-installed by Bun)

The skill automatically selects the best available compressor.

## Output Format

### Text Mode (default)

image.png → image.webp (245KB → 89KB, 64% reduction)

### JSON Mode

{
  "input": "image.png",
  "output": "image.webp",
  "inputSize": 250880,
  "outputSize": 91136,
  "ratio": 0.36,
  "compressor": "sips"
}

### Directory JSON Mode

{
  "files": [...],
  "summary": {
    "totalFiles": 10,
    "totalInputSize": 2508800,
    "totalOutputSize": 911360,
    "ratio": 0.36,
    "compressor": "sips"
  }
}

## Examples

### Compress single image

npx -y bun ${SKILL_DIR}/scripts/main.ts photo.png
# photo.png → photo.webp (1.2MB → 340KB, 72% reduction)

### Compress with custom quality

npx -y bun ${SKILL_DIR}/scripts/main.ts photo.png -q 60
# photo.png → photo.webp (1.2MB → 280KB, 77% reduction)

### Keep original format

npx -y bun ${SKILL_DIR}/scripts/main.ts screenshot.png -f png --keep
# screenshot.png → screenshot-compressed.png (500KB → 380KB, 24% reduction)

### Process entire directory

npx -y bun ${SKILL_DIR}/scripts/main.ts ./screenshots/ -r
# Processed 15 files: 12.5MB → 4.2MB (66% reduction)

### Get JSON for scripting

npx -y bun ${SKILL_DIR}/scripts/main.ts image.png --json | jq '.ratio'

## Extension Support

Custom configurations via EXTEND.md.

**Check paths** (priority order):
1. .baoyu-skills/baoyu-compress-image/EXTEND.md (project)
2. ~/.baoyu-skills/baoyu-compress-image/EXTEND.md (user)

If found, load before workflow. Extension content overrides defaults.

By Jim Liu

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/baoyu-compress-image/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/jimliu/baoyu-skills/baoyu-compress-image/SKILL.md
Cursor: ~/.cursor/skills/jimliu/baoyu-skills/baoyu-compress-image/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/jimliu/baoyu-skills/baoyu-compress-image/SKILL.md

🚀 Install with CLI:
npx skills add jimliu/baoyu-skills

Read the Master Guide: Mastering Agent Skills →

Recommended Rules

View more rules →

Recommended Workflows

View more workflows →

Optimize Images for Web

PerformanceImagesOptimization

--- description: Compress and serve images in modern formats for faster loading --- 1. **Use Next.js Image Component**: - Automatic optimization a...

Analyze Bundle Size

PerformanceNext.jsOptimization

--- description: Visualize and reduce your production build size --- 1. **Install Analyzer**: - Install the Next.js bundle analyzer. // turbo ...

Implement Request Deduplication

PerformanceAPIReact

--- description: Prevent duplicate API calls in React components --- 1. **Next.js 15 Fetch Caching**: - **Change:** `fetch` requests are no longer...

Recommended MCP Servers

View more MCP servers →

AI Endurance

Community

AI-powered training platform for runners, cyclists, and triathletes with over 20 tools for workout management, activity analysis, performance predictions, and recovery tracking.

Docker

Community

Docker MCP Server provides advanced, unified Docker management via CLI and MCP workflows, supporting containers, images, volumes, networks, and orchestration.

NASA Image MCP Server

Community

MCP server providing access to NASA's visual data APIs including Mars Rover photos, Earth satellite imagery (EPIC/GIBS), and Astronomy picture of the day. Features built-in image analysis tools with automatic format detection, compression, and base64 conversion for LLM integration.

Take It Further

Maximize your productivity with these powerful resources

📋

Define Your Standards

Set up coding standards to ensure this workflow produces consistent, high-quality results.

Browse Rules Library

📖

Master Workflows

Learn how to create custom workflows, use Turbo Mode, and build your automation library.

Complete Guide

baoyu-compress-image

Install this skill

When to Use This Skill

How to Invoke This Skill

Pro Tips

What this skill does

When not to use it

Example workflow

Prerequisites

Pitfalls & limitations

FAQ

How it compares

Source & trust

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Option B: Global Installation (All Agents)

Recommended Rules

⚡ Performance Optimization Agent - Speed Expert

Web Performance Optimization Expert

Next.js Performance Optimization

Recommended Workflows

Optimize Images for Web

Analyze Bundle Size

Implement Request Deduplication

Recommended MCP Servers

AI Endurance

Docker

NASA Image MCP Server

Take It Further

Define Your Standards

Master Workflows

How to use this Skill in Claude Code & Cursor

For Claude Code (CLI)

For Cursor & Windsurf

Source & attribution