Non-negotiable rules:

1. Read references/stack.md first to determine the project's base images, registry, and build conventions.
2. Then load only the references needed for the actual task.
3. Multi-stage builds by default — separate dependency install, build, and production stages.
4. Non-root user in production — never run containers as root. Add a user and USER directive.
5. No secrets in images — no ARG/ENV for passwords, no COPY .env, no secrets in build layers.
6. Pin base image versions — node:22-slim, not node:latest. Use digest pinning for critical images.
7. .dockerignore is mandatory — exclude node_modules, .git, .env, dist, test artifacts.
8. Frozen lockfiles in builds — --frozen-lockfile / --ci for reproducible installs.

docker

Inputs

• $request: The Docker task — Dockerfile, Compose, registry, optimization, or debugging target

Goal

Route Docker work through proven container patterns so images are small, secure, reproducible, and follow the project's infrastructure conventions.

Step 0: Read the stack contract

Always start with:

• references/stack.md

That establishes: base images, registry, build tool (Docker/BuildKit/Podman), CI integration, and locked conventions.

Success criteria: The project's container infrastructure choices are explicit before writing any Dockerfile or Compose config.

Step 1: Load only the relevant references

Use the routing table to pick reference files. Do not bulk-load the full reference tree.

Task	Read
Base images, registry, build conventions, CI	references/stack.md
Writing or editing a Dockerfile	references/dockerfile.md
Multi-stage builds, layer optimization, caching	references/multi-stage.md
docker-compose services, networking, volumes	references/compose.md
.dockerignore, build context optimization	references/build-context.md
Health checks, readiness, startup probes	references/health-checks.md
Security: non-root, read-only FS, capabilities, scanning	references/security.md
Image size optimization, distroless, slim, alpine	references/image-optimization.md
Registry: push, pull, tagging, ECR/GCR/GHCR/DockerHub	references/registry.md
BuildKit features, cache mounts, secret mounts	references/buildkit.md
CI/CD: GitHub Actions, GitLab CI, build+push pipelines	references/ci-cd.md
Debugging: logs, exec, inspect, networking issues	references/debugging.md
Language-specific: Node.js, Python, Go, Rust, Java	references/language-patterns.md
Volumes, bind mounts, tmpfs, named volumes	references/volumes.md
Networking: bridge, host, overlay, DNS, port mapping	references/networking.md

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: Only the task-relevant Docker conventions are in play.

Step 2: Implement with the core Docker guardrails

Keep these rules active:

• multi-stage builds: deps → build → production
• .dockerignore excludes everything unnecessary from build context
• pin base image tags — never :latest in production
• non-root USER in the final stage
• COPY only what's needed in each stage — not the entire repo
• health checks on every long-running service
• no secrets in ARG, ENV, or COPY — use BuildKit --mount=type=secret
• combine RUN commands to minimize layers — but keep readability
• order layers from least to most frequently changing (deps before code)

Success criteria: The container is small, secure, reproducible, and follows the project's conventions.

Step 3: Verify the build

Use the narrowest relevant verification:

• docker build succeeds
• image size is reasonable for the language/framework
• container starts and health check passes
• .dockerignore excludes the right files (docker build --dry-run or check context size)
• no secrets visible in docker history or docker inspect

Success criteria: The image builds, runs, and passes basic health validation.

Guardrails

• Do not inline the whole Docker handbook in SKILL.md.
• Do not skip references/stack.md.
• Do not use latest tags for base images in production Dockerfiles.
• Do not COPY . . without a proper .dockerignore.
• Do not run containers as root.
• Do not put secrets in build args or env vars baked into images.
• Do not add disable-model-invocation; this is a normal domain skill.

When To Load References

• references/stack.md Always.

• then only the task-relevant files under references/

Output Contract

Report:

1. which Docker references were loaded
2. the build pattern chosen (multi-stage, single, etc.)
3. the change made
4. the verification run (build success, image size, health check)