optimize-images-4k - SKILL.md Agent Skill

name: optimize-images-4k description: Recursively clean and optimize image collections for 4K landscape output with ImageMagick. Use when Codex needs to delete portrait images, delete images narrower than a required width, resize wider JPEGs to exactly 3840px while preserving aspect ratio, rename resolution suffixes such as -6000px.jpg to -3840px.jpg, remove known cover files, or verify an image collection.

Use scripts/Optimize-Images4K.ps1 instead of rebuilding fragile ImageMagick loops.

Confirm ImageMagick is installed. The script discovers magick.exe from PATH and common Windows install locations.
Run a preview first:

& scripts/Optimize-Images4K.ps1 -Root <target>

Report preview counts. Obtain confirmation before destructive work unless the user already explicitly requested deletion or conversion.
Apply the requested cleanup and conversion:

& scripts/Optimize-Images4K.ps1 -Root <target> -Apply

& scripts/Optimize-Images4K.ps1 -Root <target> -VerifyOnly

Recurse through all subdirectories.
Process .jpg and .jpeg.
Delete images where height is greater than width.
Delete images where width is less than 3840.
Resize images wider than 3840 to exactly 3840px, preserving aspect ratio.
Optimize JPEGs with metadata stripping, 4:2:0 sampling, progressive encoding, and quality 90.
Rename a trailing resolution suffix such as -6000px.jpg to -3840px.jpg.
Delete *-board.jpg, *-poster.jpg, and warning-cover.png.
Leave images already exactly 3840px wide uncompressed.

Use -Width <pixels> for a target other than 3840.
Use -Quality <1-100> to change JPEG quality.
Use -KeepPortrait, -KeepUndersized, or -KeepKnownCovers to disable deletions.
Use -NoRename to preserve filenames.

Never add -- before Windows source paths in ImageMagick conversion commands; it can strip path separators in this environment.
Replace an original only after the temporary output exists and verifies at the target width.
Never overwrite a rename collision.
Treat FAILED=0, PORTRAIT_REMAINING=0, UNDER_WIDTH_REMAINING=0, and OVER_WIDTH_REMAINING=0 as required completion evidence.