How to use the Image Compressor agent skill (baoyu-compress-image)

What an agent skill is and what this one does

An agent skill is a folder of instructions and scripts that an AI agent can load when a task matches it. This skill contains a SKILL.md file describing the task and a TypeScript script, scripts/main.ts, that does the actual compression.

Once installed, the agent can take a single image or a whole folder and make the files smaller. It converts them to WebP by default, and it can also output PNG or JPEG. It chooses the best compression tool available on your computer from sips (macOS), cwebp, ImageMagick or the Sharp library, and reports how much space was saved.

• Default output: WebP at quality 80
• Other formats: PNG and JPEG
• Reports size before and after, with the percentage reduction
• By default it replaces the original file unless you ask it to keep a copy

What you need before installing

The skill runs through the Bun runtime. The skill's metadata lists bun or npx as acceptable. If bun is installed, the agent uses it directly. If npx is available, it runs bun through npx -y bun. If neither is present, the agent will suggest installing bun.

The image tools are optional. The skill detects whatever is on your machine and uses the best one available, in the order sips, cwebp, ImageMagick, then Sharp.

• Bun, or npx (to run bun)
• Optional: sips (macOS), cwebp, ImageMagick or the Sharp library

Install the skill in Claude

Option 1, personal install: download the skill ZIP from this page and unzip it into ~/.claude/skills/ so the folder sits there as baoyu-compress-image. This makes it available across your projects.

Option 2, project install: unzip it into the .claude/skills/ folder inside a specific project. It then applies only to that project.

Option 3, Claude apps: upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need to type a command. The skill's description tells the agent when to use it, so ordinary requests work. The description lists phrases such as "compress image", "optimize image", "convert to webp" and "reduce image file size".

Name the file or folder and, if you care, the format or quality. The agent will then run the script for you.

• "Compress image.png to WebP."
• "Optimize every image in ./images/ including subfolders."
• "Convert hero.png to webp at quality 75."
• "Reduce the file size of photo.jpg but keep the original."

Run it yourself from the command line

If you prefer to run the script directly, the usage pattern is below. The {baseDir} placeholder is the skill's own folder, and ${BUN_X} is bun or npx -y bun depending on what you have installed.

Options: --output (-o) sets an output path, defaulting to the same path with a new extension. --format (-f) accepts webp, png or jpeg, default webp. --quality (-q) takes 0 to 100, default 80. --keep (-k) keeps the original, default off. --recursive (-r) processes subfolders, default off. --json switches to JSON output.

• --output / -o: output path
• --format / -f: webp, png or jpeg (default webp)
• --quality / -q: 0 to 100 (default 80)
• --keep / -k: keep the original (default false)
• --recursive / -r: include subdirectories (default false)
• --json: JSON output

Examples you can adapt

These are the examples from the skill's documentation. A single file is converted to WebP and the original is replaced. Adding -f png --keep writes a PNG and leaves the source in place. Pointing at a folder with -r -q 75 processes subfolders at quality 75. The --json flag prints machine-readable output.

A typical result line looks like this: the file is converted and the size change and percentage are printed.

Set personal defaults with EXTEND.md

You can save preferences so you do not repeat them. The skill checks three EXTEND.md locations in order and uses the first one it finds: a project file at .baoyu-skills/baoyu-compress-image/EXTEND.md, then ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-compress-image/EXTEND.md, then $HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md. If none exists, defaults apply.

The file can set a default format, a default quality and a keep-original preference.

Safety notes: overwriting, scripts and network

By default the script replaces the original image. Lossy compression is irreversible, and the default quality of 80 is lossy. Back up files first, or use the keep option. The script can delete originals, so review what the agent is about to process when working on important folders.

The skill runs scripts, so it executes code on your machine through Bun. It does not use the network, according to its metadata.

• Back up originals before batch runs
• Use --keep (or keep-original in EXTEND.md) to retain sources
• Avoid it for lossless archival or print work where quality loss matters