Skip to main content
affpapa.org
RU EN
skill CX Codex

dockerfile-optimise — Claude Code skill: Dockerfile optimization rules

A skill with 48 rules from official Docker docs: layer caching, multi-stage builds, security. Useful when writing or refactoring Dockerfiles.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill dockerfile-optimise -a claude-code
Open on GitHub

What dockerfile-optimise does

The skill hands your agent a rule set for Dockerfiles, sourced from official Docker documentation. There are 48 rules across 8 categories, ordered by impact: layer caching and multi-stage builds are marked critical, base image selection and secrets handling are high, then dependency management, instruction patterns and quality checks. Each rule carries a prefix like cache- or sec-, which makes them easy to look up.

Reference files hold the explanation and code examples for every rule. The agent reads them when it writes a new Dockerfile, scans an existing one for anti-patterns, or sets up a build in CI. Triggers fire on multi-stage work, build cache, image size and container hardening.

One catch: several BuildKit features (cache mounts, secret mounts, heredocs, COPY --link) need the syntax directive at the top of the Dockerfile. Without it those rules won't do anything at build time. Worth installing if you edit Dockerfiles by hand or through an agent on a regular basis.

What it helps with

  • order layers so the cache survives code edits
  • split build and runtime into separate stages
  • keep secrets out of ARG and ENV
  • wire up a cache mount for npm, pip or apt
  • scan a Dockerfile for anti-patterns before merge

Example prompts for the agent

  • Rewrite my Dockerfile so dependencies are copied in a layer before the source code
  • Split this Dockerfile into build and runtime stages and copy only artifacts into the final image
  • Check the Dockerfile for leaked secrets and add a non-root user

How to install dockerfile-optimise

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill dockerfile-optimise -a claude-code

2Manually: put the files in place

~/.claude/skills/dockerfile-optimise/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dockerfile-optimise/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dockerfile-optimise

How do I install dockerfile-optimise in Claude?

Run npx skills add pproenca/dot-skills --skill dockerfile-optimise -a claude-code. The skill lands at ~/.claude/skills/dockerfile-optimise/SKILL.md.

What does dockerfile-optimise do?

It gives the agent 48 Dockerfile optimization rules from official Docker docs: layer caching, multi-stage builds, base images, secrets, dependencies, instructions and validation.

Do the rules need the syntax directive?

For cache mounts, secret mounts, heredocs and COPY --link they do — without it those BuildKit features won't work. The rest of the rules apply anyway.

Source text

SKILL.md · MIT 
---
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`](references/cache-layer-order.md) - Order layers by change frequency
- [`cache-copy-deps-first`](references/cache-copy-deps-first.md) - Copy dependency files before source code
- [`cache-copy-link`](references/cache-copy-link.md) - Use COPY --link for cache-efficient layer copying
- [`cache-mount-package`](references/cache-mount-package.md) - Use cache mounts for package managers
- [`cache-apt-combine`](references/cache-apt-combine.md) - Combine apt-get update with install
- [`cache-external`](references/cache-external.md) - Use external cache for CI/CD builds
- [`cache-invalidation`](references/cache-invalidation.md) - Avoid unnecessary cache invalidation
- [`cache-minimize-layers`](references/cache-minimize-layers.md) - Consolidate related RUN instructions

### 2. Multi-Stage Builds (CRITICAL)

- [`stage-separate-build-runtime`](references/stage-separate-build-runtime.md) - Separate build and runtime stages
- [`stage-named-stages`](references/stage-named-stages.md) - Use named build stages
- [`stage-parallel-branches`](references/stage-parallel-branches.md) - Exploit parallel stage execution
- [`stage-target-builds`](references/stage-target-builds.md) - Use target builds for dev/prod
- [`stage-copy-artifacts-only`](references/stage-copy-artifacts-only.md) - Copy only final artifacts between stages
- [`stage-reusable-base`](references/stage-reusable-base.md) - Create reusable base stages

### 3. Base Image Selection (HIGH)

- [`base-minimal-image`](references/base-minimal-image.md) - Use minimal base images
- [`base-official-images`](references/base-official-images.md) - Use Docker Official Images
- [`base-pin-versions`](references/base-pin-versions.md) - Pin base image versions with digests
- [`base-arg-version`](references/base-arg-version.md) - Use ARG before FROM to parameterize base images
- [`base-rebuild-regularly`](references/base-rebuild-regularly.md) - Rebuild images regularly with --pull
- [`base-distroless`](references/base-distroless.md) - Use distroless or scratch images for production

### 4. Build Context Management (HIGH)

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

### 5. Security & Secrets (HIGH)

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

### 6. Dependency Management (MEDIUM-HIGH)

- [`dep-cache-mount-apt`](references/dep-cache-mount-apt.md) - Use cache mount for apt package manager
- [`dep-cache-mount-npm`](references/dep-cache-mount-npm.md) - Use cache mount for npm, yarn, and pnpm
- [`dep-cache-mount-pip`](references/dep-cache-mount-pip.md) - Use cache mount for pip
- [`dep-version-pin`](references/dep-version-pin.md) - Pin package versions for reproducibility
- [`dep-cleanup-caches`](references/dep-cleanup-caches.md) - Clean package manager caches in the same layer

### 7. Instruction Patterns (MEDIUM)

- [`inst-json-cmd`](references/inst-json-cmd.md) - Use JSON form for CMD and ENTRYPOINT
- [`inst-healthcheck`](references/inst-healthcheck.md) - Define HEALTHCHECK for container orchestration
- [`inst-heredoc-scripts`](references/inst-heredoc-scripts.md) - Use heredocs for multi-line scripts
- [`inst-entrypoint-exec`](references/inst-entrypoint-exec.md) - Use exec in entrypoint scripts
- [`inst-workdir-absolute`](references/inst-workdir-absolute.md) - Use absolute paths with WORKDIR
- [`inst-copy-over-add`](references/inst-copy-over-add.md) - Prefer COPY over ADD

### 8. Quality & Validation (MEDIUM)

- [`lint-build-checks`](references/lint-build-checks.md) - Enable Docker build checks
- [`lint-pipefail`](references/lint-pipefail.md) - Use pipefail for piped RUN commands
- [`lint-labels`](references/lint-labels.md) - Use standard labels for image metadata
- [`lint-sort-arguments`](references/lint-sort-arguments.md) - Sort multi-line arguments alphabetically
- [`lint-single-concern`](references/lint-single-concern.md) - One concern per container

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for DevOps and infrastructure →
docker-build-strategies docker A skill that guides your coding agent in writing, reviewing, and optimizing Dockerfiles using BuildKit best practices. Helpful when builds run slowly or images grow too heavy. CX Codex +1 1,200installs dockerfile-generator akin-ozer A skill that writes production-ready Dockerfiles and .dockerignore, validates them, then fixes what the validator flags. Handy when you need to containerize a service without hand-tuning layers. CX Codex +1 699installs dockerfile-optimizer patricio0312rev A skill that rewrites your Dockerfile around multi-stage builds: smaller images, faster builds, working layer cache. Useful when the image has bloated or CI drags. CX Codex +1 530installs dockerfile-validator akin-ozer Validates Dockerfiles for syntax, security flaws, and build practices using a structured validation script. Useful for hardening images before CI/CD merges. CX Codex +1 740installs docker-best-practices JosiahSiegel A Docker skill that guides your agent through Dockerfiles, base image choice and production container setup. CX Codex +1 938installs docker-development Alireza Rezvani This skill reviews Dockerfiles, Compose files, and containers for build, image-size, and security issues. Use it when setting up or cleaning up containerized projects. 702installs

From the same set46

react-optimise A skill that walks through React app performance: React Compiler, bundle size, rendering, data fetching, Core Web Vitals. Useful when your app feels slow. CX Codex +1 396installs rails-hotwire A skill with Hotwire rules for Rails: Turbo Drive, Frames, Streams, Turbo 8 morphing and Stimulus controllers. Useful when writing or refactoring interactive pages. CX Codex +1 370installs nginx-c-module-design A skill for anyone writing nginx C modules: it helps you decide what to expose as directives, how to name them and where they belong. Most useful while the module's config interface is still being shaped. CX Codex +1 352installs nginx-c-modules A skill that feeds your agent 49 rules for nginx C module work: pool memory, request lifecycle, config merging. Useful when you write or refactor a handler, filter or upstream. CX Codex +1 349installs uniwind A skill with 45+ rules for Uniwind, the Tailwind bindings for React Native. Useful when setting up a project, building themes or migrating from NativeWind. CX Codex +1 341installs ast-grep A skill with community best practices for writing, reviewing and debugging ast-grep rules for code search, linting and rewriting. CX Codex +1 332installs 37signals-rails A rule set for Ruby on Rails the 37signals way: vanilla Rails, CRUD controllers, rich domain models, Hotwire. Useful when you write or refactor code and want to stay in that school. CX Codex +1 329installs mui-base A skill with 48 rules for building headless React component libraries the MUI Base UI way. Useful when logic and styling stay apart. CX Codex +1 328installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor