---

name: dockerfile-optimise description: Dockerfile optimization guidelines from official Docker documentation. This skill should be used when writing, reviewing, or refactoring Dockerfiles to ensure optimal build time, image size, security, and robustness. Triggers on tasks involving Dockerfile creation, Docker image builds, container optimization, multi-stage builds, build cache, or Docker security hardening.

Dockerfile Optimization Best Practices

Comprehensive Dockerfile optimization guide sourced exclusively from official Docker documentation. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Dockerfiles or modifying existing ones
• Optimizing Docker build times (layer caching, cache mounts, context management)
• Reducing Docker image size (multi-stage builds, minimal base images)
• Hardening container security (secret mounts, non-root users, attestations)
• Setting up CI/CD pipelines with Docker builds
• Reviewing Dockerfiles for anti-patterns

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Layer Caching & Ordering	CRITICAL	cache-
2	Multi-Stage Builds	CRITICAL	stage-
3	Base Image Selection	HIGH	base-
4	Build Context Management	HIGH	ctx-
5	Security & Secrets	HIGH	sec-
6	Dependency Management	MEDIUM-HIGH	dep-
7	Instruction Patterns	MEDIUM	inst-
8	Quality & Validation	MEDIUM	lint-

Quick Reference

1. Layer Caching & Ordering (CRITICAL)

• cache-layer-order - Order layers by change frequency
• cache-copy-deps-first - Copy dependency files before source code
• cache-copy-link - Use COPY --link for cache-efficient layer copying
• cache-mount-package - Use cache mounts for package managers
• cache-apt-combine - Combine apt-get update with install
• cache-external - Use external cache for CI/CD builds
• cache-invalidation - Avoid unnecessary cache invalidation
• cache-minimize-layers - Consolidate related RUN instructions

2. Multi-Stage Builds (CRITICAL)

• stage-separate-build-runtime - Separate build and runtime stages
• stage-named-stages - Use named build stages
• stage-parallel-branches - Exploit parallel stage execution
• stage-target-builds - Use target builds for dev/prod
• stage-copy-artifacts-only - Copy only final artifacts between stages
• stage-reusable-base - Create reusable base stages

3. Base Image Selection (HIGH)

• base-minimal-image - Use minimal base images
• base-official-images - Use Docker Official Images
• base-pin-versions - Pin base image versions with digests
• base-arg-version - Use ARG before FROM to parameterize base images
• base-rebuild-regularly - Rebuild images regularly with --pull
• base-distroless - Use distroless or scratch images for production

4. Build Context Management (HIGH)

• ctx-dockerignore - Use .dockerignore to exclude unnecessary files
• ctx-bind-mounts - Use bind mounts instead of COPY for build-only files
• ctx-minimize-context - Keep build context small
• ctx-syntax-directive - Use syntax directive for latest BuildKit features (prerequisite for cache mounts, secret mounts, heredocs, COPY --link)

5. Security & Secrets (HIGH)

• sec-secret-mounts - Use secret mounts for sensitive data
• sec-non-root-user - Run as non-root user
• sec-no-secrets-in-args - Never pass secrets via ARG or ENV
• sec-ssh-mounts - Use SSH mounts for private repository access
• sec-attestations - Enable SBOM and provenance attestations
• sec-no-unnecessary-packages - Avoid installing unnecessary packages
• sec-ephemeral-containers - Design ephemeral, stateless containers

6. Dependency Management (MEDIUM-HIGH)

• dep-cache-mount-apt - Use cache mount for apt package manager
• dep-cache-mount-npm - Use cache mount for npm, yarn, and pnpm
• dep-cache-mount-pip - Use cache mount for pip
• dep-version-pin - Pin package versions for reproducibility
• dep-cleanup-caches - Clean package manager caches in the same layer

7. Instruction Patterns (MEDIUM)

• inst-json-cmd - Use JSON form for CMD and ENTRYPOINT
• inst-healthcheck - Define HEALTHCHECK for container orchestration
• inst-heredoc-scripts - Use heredocs for multi-line scripts
• inst-entrypoint-exec - Use exec in entrypoint scripts
• inst-workdir-absolute - Use absolute paths with WORKDIR
• inst-copy-over-add - Prefer COPY over ADD

8. Quality & Validation (MEDIUM)

• lint-build-checks - Enable Docker build checks
• lint-pipefail - Use pipefail for piped RUN commands
• lint-labels - Use standard labels for image metadata
• lint-sort-arguments - Sort multi-line arguments alphabetically
• lint-single-concern - One concern per container

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information