Docker Optimizer

Audit a Docker/Compose setup, report what is slow, large or unsafe and why, agree a plan, then change it. Order: evidence, approval, edits. Image and runtime changes affect deployability and security; nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the Dockerfiles/compose files and record: Docker Engine/BuildKit version, base images, build context, target platforms, registry, runtime user, orchestrator (Compose/K8s/PaaS), and deploy command.
• Run python <skill-dir>/scripts/audit.py <repo-root> -- static scan for floating tags, missing users/healthchecks, apt/npm cache waste, secrets, privileged/host mounts, docker.sock exposure, compose limits and build-cache gaps, with file:line evidence. Use --json to post-process.
• Classify the pain: image size/pull time, build time/cache, startup, runtime security, compose reliability, or supply chain. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (docker buildx build, docker image history, dive, docker scout/Trivy/Grype, Compose logs).

2. Audit

The script finds cheap leads; you find the rest by reading the Dockerfile, .dockerignore, compose file and runtime entrypoint. Load only what applies:

Measure, never guess. Build the real target with BuildKit, compare docker image history/dive and cold-pull times, run the container with production limits and measure startup/health. A clean build cache hides transfer and layer costs; report cold and warm.

Mark each finding Confirmed (build/image inspect/runtime evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as DOCKER_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, rollback). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- pin images, add .dockerignore, reorder layers, npm ci/pip --no-cache-dir, clean apt lists, non-root USER, exec-form CMD, healthcheck, compose limits. Low risk.
2. Structural -- multi-stage build, distroless/slim runtime, cache mounts, Buildx cache import/export, compose healthchecks/depends_on, read-only rootfs/cap drop, secrets mounts, split build/runtime images. Name each behavior change.
3. Heavy -- base-image family change, rootless/userns-remap, multi-arch, registry/SBOM policy, orchestrator migration. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: docker buildx build for the target platform, docker run health/startup check, compose config/up, and the relevant scan. A break must trace to one change. Do not mix a base-image migration with optimization edits. If a change alters the runtime user, entrypoint, exposed ports or secrets, stop and ask.

6. Verify and wrap up

Re-measure the same target: image size (compressed/uncompressed), layer count, cold build/pull/start, cache hit, CPU/memory under load, scan findings and SBOM/provenance. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• The smallest image is the one without build tools. Multi-stage + minimal runtime.
• Cache is layer order. Copy manifests/lockfiles before source; use BuildKit cache mounts.
• Run as non-root. No secrets in layers; read-only rootfs where possible.
• Pin what you ship. Tags/digests, not latest; reproducible builds.
• Compose is production config too. Healthchecks, limits, dependencies and networks are not optional.
• Scan and sign. SBOM/provenance and a scanner in CI; a clean image is part of the artifact.
• Measure cold and warm. Build cache, pull time and startup are different costs.
• Docs move. Check the Engine 29/BuildKit/Compose docs for the installed version.