Asset optimization

Asset Optimization

The smallest asset that still serves its purpose. Measure the bytes, not the intent.

An asset is a media file whose bytes we shrink without changing what it is for. This skill is a lookup keyed on the asset's kind that decides format, tool, and whether the pass may lose information, so the file ends up as small as it can be while still doing its job on the surface it will be presented on.

Structure. Each kind is an executor under executors/<kind>/, a folder of standardized organs: procedure.md (the how-to, including prerequisites and cross-kind redirects), cookbook.md (curated verbatim recipes), targets.md (surface to format), and expectations.md (measured size data). The cross-cutting references at the root are tools.md (the tool manifest, defined once because one tool serves many kinds), surface.md (which surface), classify.md (how to detect a file's kind), batch.md (repository operation, originals, idempotence, report), and cookbook.md (the recipe rubric and an index of every kind's cookbook). This two-level structure is deliberately heavier than the flat references/ layout of the repo's other skills, because this skill has more orthogonal axes than any sibling: kind, surface, fidelity intent, and tool.

Fidelity intent (decide first; it gates every tool)

Intent	Meaning	Consequence
Lossless-required	a pixel, sample, path, or vertex is load-bearing (design fidelity, a diff, evidence)	only lossless tools; never quantize or re-encode lossy
Lossy-acceptable	the asset carries an impression, not exact bytes (walkthrough, delivery, thumbnail)	lossy tools are in play, tuned to "looks the same to the viewer who judges it"

If compression would change what the asset is for, it is lossless-required by definition. Optimize for "looks exactly the same to the person who will judge it."

Surface decides format

The presentation surface, not the source format, decides the output. Determine the surface once (surface.md); then each kind's targets.md maps that surface to its own output. For the alternative-format kinds (raster, animation, video) the surface genuinely selects the format; for the fixed-format kinds (vector, audio, font, document, model) the format is largely pinned and targets.md instead chooses the tuning depth (dpi, subset, decoder, bitrate) on that kind's own axis.

Detect and acquire

Executor posture: probe for the binary, install it if missing, and select the best available tool. Tools, install hints, and their gotchas live once in tools.md; each executor's procedure.md names its prerequisites and links there. Never fail because a tool is absent when it can be acquired; never silently skip a tool and claim success. Installing a system package is a consequential action; when a tool is missing, prefer detection and a clear ask before a global or sudo install, and record what was installed.

Measure, validate, and never regress

Record before and after bytes, and validate the output decodes and preserves what fidelity intent requires (structure, alpha, color profile, animation, dimensions). Keep the result only if it is smaller AND passes validation; otherwise keep the original. An optimization that grows the file, or degrades a lossless-required asset, or produces a file that will not decode, is a failure. Reported numbers are observed bytes, never estimates.

Originals. Write results to a new path; do not edit the source in place, and keep the original whenever the result is not smaller and valid. In-place replacement is only safe for a same-format pass (PNG to PNG); a format or kind redirect changes the extension, so it must emit a new file and leave rewiring the references (<img src>, url(), imports) to the caller, never silently deleting the source (see batch.md).

Idempotence. Do not re-optimize an already-optimized asset; a second lossy pass loses quality for no size win. In batch, skip inputs whose content hash is unchanged since the last run (batch.md).

Batch

Optimizing a repository is the point, not a special case. Walk the tree, skip build output and dependency trees, classify each file (classify.md), route it through the same per-file decision, and emit a report. The full walk, skip-list, originals policy, idempotence guard, and report format live in batch.md.

Dispatch: asset kind to executor

Kind	Members	Executor
raster	PNG, JPEG, WebP, AVIF, JXL (HEIC/TIFF/BMP as input)	executors/raster/
vector	SVG	executors/vector/
animation	GIF, animated WebP, APNG	executors/animation/
video	MP4/H.264, HEVC, VP9, AV1, WebM, MOV	executors/video/
audio	WAV, AIFF, MP3, AAC, Opus, Ogg, FLAC	executors/audio/
model	glTF, GLB (embedded textures)	executors/model/
document	PDF	executors/document/
font	TTF, OTF, WOFF, WOFF2	executors/font/

The source kind may be wrong

The kind you were handed is not always the kind the asset should be. Each executor's procedure.md ends with a redirect section: a photographic PNG-24 with no alpha belongs in raster as a JPEG or WebP, not a PNG; a long, photographic GIF belongs in video; a rasterized icon belongs in vector; an icon font used for a few glyphs belongs in vector. Follow the redirect before optimizing the wrong thing well.

The loop

1. Assess the surface (surface.md); ask when too vague.
2. Classify the asset's kind (classify.md); follow a cross-kind redirect if the source is wrong for the job.
3. Pick fidelity intent (lossless-required vs lossy-acceptable).
4. Inspect the source (ffprobe / identify / MediaInfo / ExifTool) to record its starting shape.
5. Acquire the tool for that kind and format (tools.md).
6. Run the pass to a new output, never over the source (the kind's procedure.md and cookbook.md).
7. Validate the output decodes and preserves what fidelity intent requires.
8. Keep the result only if it is smaller AND valid; record before/after (this extends the kind's expectations.md with real data).

When something is missing or wrong

This skill is a draft that grows by use. While optimizing, if you find a command that no longer works (a tool changed or dropped a flag) or you discover a recipe, tool, or kind the skill lacks, you may open an issue against the skill's repository (simiancraft/simiancraft-skills) to report it. Ask the user's permission first, and only then file a terse issue: the tool and its version, the exact command, and what failed or what is missing. Do not open an issue unprompted, and do not file a duplicate for a gap already reported. Maintainers turn these into fixes (see AGENTS.md).