| 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
