imagemin-skill

A reusable AI skill for image compression using imagemin.

This skill provides instructions, plugin references, usage patterns, and best practices for compressing JPEG, PNG, GIF, SVG, and WebP images in Node.js projects — designed to be used with any AI assistant that supports custom skills or system prompts.

Key Features:

• 📚 Complete imagemin plugin reference and usage patterns
• 🚀 Performance optimization and batch processing strategies
• 🛠️ Ready-to-use CLI compression tool
• 🤖 AI-friendly with flexible command-line interface
• 📊 Real-world compression ratio examples

🔧 Installation

Via Skills CLI (Recommended)

npx skills add iShawnWang/imagemin-skill

Manual Installation

Clone or download this repository to your AI assistant's skills directory.

📦 Installation

Install imagemin and common plugins:

# Using npm
npm install imagemin imagemin-mozjpeg imagemin-pngquant imagemin-gifsicle imagemin-svgo imagemin-webp

# Using yarn
yarn add imagemin imagemin-mozjpeg imagemin-pngquant imagemin-gifsicle imagemin-svgo imagemin-webp

# Using pnpm
pnpm add imagemin imagemin-mozjpeg imagemin-pngquant imagemin-gifsicle imagemin-svgo imagemin-webp

# For pnpm 10+ (binary builds)
pnpm approve-builds

When using pnpm, if you see a warning like:

Ignored build scripts: cwebp-bin, gifsicle, mozjpeg, pngquant-bin

run pnpm approve-builds once in the project and approve the image binaries so that pngquant, mozjpeg, and friends can be executed by the CLI.

Note: imagemin v8+ is ESM-only. If your project uses CommonJS, install imagemin@7.

🚀 Quick Start

Basic Example: Compress an Image Directory

Create a compress.js file:

import imagemin from 'imagemin';
import imageminMozjpeg from 'imagemin-mozjpeg';
import imageminPngquant from 'imagemin-pngquant';

const files = await imagemin(['src/images/*.{jpg,png}'], {
  destination: 'dist/images',
  plugins: [
    imageminMozjpeg({ quality: 75 }),
    imageminPngquant({ quality: [0.65, 0.80] }),
  ],
});

console.log(`✅ Compressed ${files.length} files`);

Run it:

node compress.js

Multiple Format Support

import imagemin from 'imagemin';
import imageminMozjpeg from 'imagemin-mozjpeg';
import imageminPngquant from 'imagemin-pngquant';
import imageminGifsicle from 'imagemin-gifsicle';
import imageminSvgo from 'imagemin-svgo';

await imagemin(['src/**/*.{jpg,jpeg,png,gif,svg}'], {
  destination: 'dist/images',
  plugins: [
    imageminMozjpeg({ quality: 80 }),
    imageminPngquant({ quality: [0.65, 0.80] }),
    imageminGifsicle({ optimizationLevel: 2 }),
    imageminSvgo(),
  ],
});

📚 Contents

• SKILL.md — Complete plugin reference, usage patterns, and best practices
• scripts/ — Ready-to-use compression tools

💡 Use Cases

This skill is useful for:

1. Build Process Integration

Automatically compress images in your build scripts to reduce bundle size.

2. Batch Processing

One-time compression of entire image directories for project optimization or maintenance.

3. API Services

Real-time image compression for uploads in Express/Koa applications.

4. Development Tools

Integration with Webpack, Vite, Gulp, and other build tools.

🔧 How to Use This Skill

With AI Assistants

Attach or reference SKILL.md in your AI assistant's skill/context configuration. Your assistant will be able to:

• Provide imagemin best practice recommendations
• Generate compression scripts tailored to your project
• Answer image compression questions
• Suggest appropriate plugins and parameters

As Standalone Documentation

SKILL.md can also be used as a standalone reference, containing:

• ✅ Detailed plugin parameter documentation
• ✅ Common usage patterns and code examples
• ✅ Compression quality recommendations and best practices
• ✅ Error handling and performance optimization tips

❓ FAQ

Q: Why am I getting ESM-related errors?

A: imagemin v8+ is ESM-only. Solutions:

• Add "type": "module" to your package.json
• Or install v7: npm install imagemin@7 (or yarn/pnpm equivalent)

Q: How do I avoid over-compression?

A: Follow these guidelines:

• Set JPEG quality between 75-85
• Set PNG quality to [0.65, 0.80]
• Don't re-compress already compressed images

Q: How do I handle large batches of images?

A: Process in chunks to avoid memory exhaustion, or use streaming. See the best practices section in SKILL.md.

📄 License

MIT