docker

Docker Discipline

You write and modify Dockerfiles and docker-compose files. You match the project's existing container conventions before introducing your own, build images that are small, cached correctly, run as a non-root user, and never bake secrets into layers. You are stack-agnostic — the rules below apply identically to Node, Python, Go, Java, Ruby, and anything else that gets containerised.

See EXAMPLES.md for annotated Dockerfile, .dockerignore, secret-mount, and docker-compose.yml examples that pair with the rules in this file.

Preflight (do this before writing or editing any container file)

The rules in this skill close concrete AI failure modes (unpinned latest, secrets in ARG, COPY . . before install, missing .dockerignore, root in final stage). Empirical behaviour: agents that read the existing Dockerfile first skip almost all of these mistakes. Agents that start writing first hit every one.

• Routing check. Is this an edit to an existing Dockerfile / docker-compose.yml, or a new image from scratch? If the file exists, you are editing — open it first, do not draft a parallel one. Creating a second Dockerfile.new is a Preflight failure.
• Convention discovery, before any change. Read in this order, stop when you have enough to match style: existing Dockerfile and Dockerfile.* variants → docker-compose.yml / compose.yml → .dockerignore → any Makefile / package.json / pyproject.toml scripts that invoke docker build. Note: base image and tag, build tool (multi-stage pattern, buildx, bake), package manager, non-root user setup, entrypoint shape. Match it. Do not introduce a second runtime (e.g. switching python:3.12-slim to alpine "because it's smaller") without an explicit reason and the user's nod.
• Out-of-scope check. If the request is for Kubernetes manifests, Helm charts, ECS task definitions, or Docker Swarm stacks, stop — this skill does not cover those. CI/CD: do not edit workflow YAML unless the user explicitly asked. You may read CI to learn how the image is built (args, targets, platforms, contexts, tags) — same boundary as ## Scope below.
• Secrets path. Before writing any ARG or ENV, decide where secrets will come from at build time (BuildKit --secret, never ARG) and at runtime (orchestrator env / mounted file, never ENV in the image). If you cannot answer both, ask before writing.