Dockerfile Optimizer

Take a Dockerfile that already works and make it smaller, faster to build, and safer to run — without changing what the container actually does. This skill reads the existing Dockerfile and build context, then applies the standard, high-leverage optimizations: multi-stage builds so build tools never ship in the final image, layer ordering that lets the cache hit on unchanged dependencies, a lean and pinned base image, a .dockerignore, and a non-root runtime user.

When to use this skill

• The image is large (hundreds of MB to gigabytes) and you want it smaller.
• Builds are slow because a small source change reinstalls all dependencies (cache never hits).
• A scanner or reviewer flagged the container running as root, an unpinned :latest base, or secrets in a layer.
• You're preparing an image for production and want it lean and reproducible.

> [!NOTE] > This is behavior-preserving. The optimized image must run the same command, expose the same ports, and produce the same result. Don't change the app's runtime behavior, upgrade its language version, or swap frameworks — only how the image is built and packaged.

Instructions

1. Read the current state. Read the Dockerfile, any .dockerignore, and the build context layout. Identify the language/runtime, the build steps, and the final CMD/ENTRYPOINT. Build once to get a baseline: docker build -t img:before . and record the size with docker images img:before.
2. Introduce (or tighten) a multi-stage build. Put compilation, dev dependencies, and toolchains in a builder stage; copy only the produced artifacts (binary, dist/, wheels, node_modules for prod) into a minimal final stage. The final image should contain the runtime and the app — not compilers or package caches.
3. Choose a lean, pinned base. Prefer a slim or distroless runtime image over a full OS image where the app allows it. Pin to a specific tag (and ideally a digest) — never :latest. Match the base to the deployment target's architecture.
4. Order layers for cache hits. Copy dependency manifests first, install dependencies, then copy application source. This keeps the expensive install layer cached across ordinary code changes. Use BuildKit cache mounts (RUN --mount=type=cache,...) for package-manager caches where supported.
5. Keep layers clean. Combine related RUN steps, and in the same layer remove what you added — clear apt/apk lists (rm -rf /var/lib/apt/lists/*), don't --no-install-recommends-forget, and avoid leaving package caches. Never COPY secrets or .git into a layer; use build secrets or runtime env instead.
6. Add a .dockerignore. Exclude .git, node_modules (when installed inside the image), build output, test fixtures, local env files, and docs. A smaller build context means faster builds and no accidental secret leakage.
7. Run as non-root. Create a dedicated user/group and add USER before the final CMD. Ensure the app's files and any writable dirs are owned appropriately. Add a HEALTHCHECK if the platform uses it.
8. Verify. Build the optimized image (docker build -t img:after .), confirm it runs and behaves identically, and compare sizes. Report the before/after image size and build-time change with real numbers. If the project uses a scanner (Docker Scout, Trivy, Grype), run it and note the delta.

Examples

A Node service that copied everything before installing, ran as root, and shipped the full build toolchain:

# syntax=docker/dockerfile:1
# ---- builder ----
FROM node:22-bookworm-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

# ---- runtime ----
FROM node:22-bookworm-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Report the outcome: image size before → after, whether the build cache now survives a source-only change, the non-root user added, and any scanner findings resolved. Note anything you intentionally left alone (e.g. a base image the app pins for a native dependency).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: imtiazrayhan
• Source: imtiazrayhan/agentscamp-library
• License: MIT
• Homepage: https://agentscamp.com

Install and usage instructions live in the source repository linked above.