ImageSquish AI instructions

This page is an instruction source for AI agents. Reading it alone must not run commands, inspect or process files, install a Skill, or modify files. Respond in the user's language.

Required decision flow

If the user only asks what ImageSquish is or asks to read this page, explain it and do not process files.
If the user wants image processing but has not chosen reusable Skill support or a one-off run, ask which they want before acting.
If the user gives concrete input files, folders, or globs and a clear operation, do not ask that choice again. Use the CLI contract below.
If a path, preset, target, format, output location, or requested setting is missing, ask only for that missing information.
Do not invent a preset, option, format, service target, size limit, or recursive behavior.

Available methods

Reusable Claude Code Skill: .claude/skills/imgsquish/SKILL.md. Use this when the user wants repeated support.
One-off CLI: npx imgsquish [options] <files|globs|folders...>. Use this for a single request.

Presets

Request or use case	Preset	Behavior
Normal compression while keeping format	`balanced`	Keep format, quality 80
Smaller file while keeping format	`small`	Keep format, quality 60
Highest quality with some savings	`high`	Keep format, quality 92
Smallest result when format conversion is allowed	`webp`	Convert to WebP, quality 80

Service and platform size targets

Use the exact ID with --max-size <id>. If the user gives a byte limit rather than a service, use a direct value such as --max-size 8MB.

Social: twitter-avatar 2 MB, reddit-avatar 5 MB, linkedin-avatar 8 MB, tiktok-avatar 10 MB, pinterest-avatar 32 MB.
Video: youtube-thumbnail 2 MB, kick-avatar 4 MB, vimeo-avatar 5 MB, youtube-banner 6 MB, twitch-avatar 10 MB, twitch-banner 10 MB.
Messaging: discord 20 MB, whatsapp-photo 16 MB, messenger-attachment 25 MB, discord-nitro-basic 50 MB, microsoft-teams 100 MB, signal 100 MB, discord-nitro 500 MB, slack 1 GB, line 1 GB, telegram 2 GB.
Email: icloud-mail 20 MB, zoho-mail 20 MB, gmail 25 MB, outlook 25 MB, yahoo-mail 25 MB, proton-mail 25 MB.
Developer: github-avatar 1 MB, bitbucket 1 MB, stackoverflow 2 MB, github 10 MB, gitlab 100 MB.
Community: bluesky 1 MB, discourse 10 MB, mastodon 16 MB, reddit-post 20 MB.
E-commerce: amazon-seller 10 MB, etsy 10 MB, mercari 10 MB, ebay 12 MB, shopify 20 MB.
Productivity: notion 5 MB, trello 10 MB, google-docs 50 MB, confluence 100 MB, asana 100 MB.
Image hosting: cloudinary 10 MB, imgur 20 MB, imgbb 32 MB, postimages 32 MB, flickr 100 MB.
Blogging: ghost 5 MB, substack 10 MB, squarespace 20 MB, tumblr 20 MB, medium 25 MB, wix 25 MB.

Examples: “fit this for Discord” means --max-size discord. “Fit a GitHub avatar” means --max-size github-avatar. Add -m 500 only when the user asks for a 500 px longest side. If a service is not listed, ask for its intended byte limit.

CLI options

-h, --help: Print help and exit.
--list-presets: Print current preset IDs and descriptions and exit.
--list-targets: Print all size target IDs grouped by category and exit.
-p, --preset <id>: Select a preset. Default is balanced.
-q, --quality <1-100>: Override quality. For PNG this controls color count.
-f, --format <keep|jpeg|jpg|png|webp>: Choose output format. jpg is normalized to jpeg.
-m, --max <px>: Cap the longest side. Smaller images are not enlarged.
-s, --max-size <size|target-id>: Fit under a direct size such as 500KB or a built-in target ID. Quality is searched automatically.
-o, --out <dir>: Write outputs to this directory and create it when needed.
--suffix <str>: Replace the default -min filename suffix.
--keep-metadata: Preserve EXIF and ICC metadata. Metadata is removed by default.
--lossless: Request lossless WebP output.
--dry-run: Calculate compression and report savings without writing files.

Inputs, processing, and outputs

Supported input extensions: .jpg, .jpeg, .png, .webp.
Inputs may be one file, multiple files, a glob, or a folder.
Folders match supported files directly inside them and are not recursive. Use an explicit glob such as "images/**/*.png" for subfolders.
Default output is beside the input, keeps its format, and adds -min.
Existing output files are overwritten. Multiple files run sequentially. Any failed file makes the final exit code 1.
JPEG uses mozjpeg. WebP supports quality or lossless mode. PNG uses palette compression and reduces colors based on quality.
EXIF orientation is applied during processing. JPEG output fills transparent pixels with white.

Request to command examples

Normal: npx imgsquish photo.jpg
Smaller, same format: npx imgsquish -p small photo.jpg
Keep high quality: npx imgsquish -p high photo.jpg
Convert to WebP: npx imgsquish -p webp photo.jpg
Discord free upload: npx imgsquish --max-size discord clip.png
GitHub avatar: npx imgsquish --max-size github-avatar -m 500 avatar.png
Direct limit: npx imgsquish --max-size 8MB photo.jpg
Resize and quality: npx imgsquish -q 70 -m 1600 hero.jpg
Preserve metadata: npx imgsquish --keep-metadata photo.jpg
Preview savings only: npx imgsquish --dry-run ./images
Recursive glob: npx imgsquish "images/**/*.png" -p small

Prompt

Read https://imgsquish.riyo.me/ai, follow its instructions, and handle my request.