convert-png-to-webp

name	convert-png-to-webp
description	Use this skill when converting PNG images in a directory tree to lossless WebP in place with `cwebp`, preserving original file timestamps, deleting the source PNG files only after successful conversion, and reporting the processed image count.
license	MIT
metadata	{"author":"cssmagic"}

Convert PNG to WebP

Purpose

Convert PNG files inside one directory tree to same-location .webp files:

• Convert PNG files to lossless WebP.
• Preserve original modification time and, on macOS, creation time.
• Delete each source PNG only after its WebP replacement is complete.
• Report how many PNG files were processed.

Required Input

Each run needs one directory to process.

If the directory is missing or ambiguous, ask the user for the path before running commands.

Normalize ~ and relative paths to an absolute path before reporting or running the script.

Defaults

Treat PNG extensions case-insensitively.

Map each PNG to a same-directory, same-basename .webp file.

Do not overwrite existing .webp files unless the user explicitly allows overwrite behavior. If a mapped .webp already exists, report the exact PNG and WebP paths and stop before converting anything.

Reject symlinked PNG files before writing, because deleting a symlink after conversion is easy to misread.

Prerequisites

Use the official WebP CLI:

command -v cwebp

The bundled script requires Python 3:

command -v python3

On macOS, creation-time preservation requires:

command -v GetFileInfo
command -v SetFile

If those macOS timestamp tools are unavailable, stop before converting anything.

Workflow

Set the directory from the user's provided path:

dir="/absolute/path/to/directory"

Run the bundled script from this skill directory:

python3 scripts/convert_png_to_webp.py "$dir"

Only pass --overwrite if the user explicitly permits replacing existing mapped WebP files:

python3 scripts/convert_png_to_webp.py --overwrite "$dir"

The script performs preflight checks before writing:

• required commands
• directory existence
• existing mapped WebP files
• target path collisions, including case-insensitive collisions
• symlinked PNG files

During conversion, the script writes a temporary WebP beside the source file, syncs timestamps, atomically moves it into place, and only then deletes the source PNG.

Reporting

Summarize with:

• directory
• PNG files found
• converted WebP files
• deleted original PNG files
• failed files, if any
• timestamp failure count
• whether macOS creation times were synced