docker-expert

Provides Docker reference guidance covering BuildKit, multi-stage builds, Compose v2, and container security.

Updated Jun 24, 2026
One-click install
npx skills add https://github.com/psmfd/pi-config --skill docker-expert-psmfd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docker-expert
Source: https://github.com/psmfd/pi-config/tree/main/agent/skills/docker-expert
Command: npx skills add https://github.com/psmfd/pi-config --skill docker-expert-psmfd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Docker configuration involves many subtle traps — silently ignored secret mounts, broken cache behavior in CI, rootless BuildKit setup quirks, and Compose v1-to-v2 migration differences. This Skill gives an AI agent a structured, read-only Docker reference so it can produce correct Dockerfiles, build commands, and Compose files without trial and error. ## Core Features & Use Cases - BuildKit and Rootless Builds: Covers the # syntax directive, version pinning, rootless buildkitd setup, socket paths, and feature support matrices. - Secret and Cache Mounts: Documents --mount=type=secret and --mount=type=cache patterns, sharing modes, and the silent-failure trap when the syntax directive is missing. - Multi-Stage and Multi-Platform Builds: Explains stage ordering, COPY --from, QEMU vs cross-compilation trade-offs, and platform variables like TARGETARCH. - Security and Compose v2: Details non-root users, .dockerignore, runtime hardening flags, health-check dependencies, and profiles. - Use Case: Ask the agent to write a multi-stage Dockerfile for a Go service with secret mounts for a private module proxy and a rootless BuildKit build command — it produces correct syntax on the first attempt. ## Quick Start Ask the agent to write a secure multi-stage Dockerfile with BuildKit cache and secret mounts for your application.

Frequently Asked Questions about docker-expert

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I use BuildKit secret mounts in a Dockerfile?▼

Add `# syntax=docker/dockerfile:1` as the first line, then use `RUN --mount=type=secret,id=mytoken` and pass the value with `docker buildx build --secret id=mytoken,src=./token.txt`. Secrets exist only during the RUN instruction and are never committed to image layers.

Why is my Docker secret mount not working?▼

The most common cause is a missing `# syntax=docker/dockerfile:1` directive. Without it, the legacy builder silently ignores the `--mount` flag, so the RUN executes but the secret file does not exist, with no error or warning.

How do I build multi-platform Docker images with buildx?▼

Run `docker buildx build --platform linux/amd64,linux/arm64 --push .` after setting up QEMU with `tonistiigi/binfmt`. For faster builds, use cross-compilation with `FROM --platform=$BUILDPLATFORM` and the TARGETOS/TARGETARCH build arguments.

Does rootless BuildKit support all Docker build features?▼

Rootless BuildKit fully supports image builds, cache mounts, and secret mounts. Multi-platform builds require running `tonistiigi/binfmt` as root once, overlay filesystem needs kernel 5.11 or newer, and privileged operations like binding ports below 1024 are limited.

What is the difference between Docker Compose v1 and v2?▼

Compose v2 is a Go-based Docker CLI plugin invoked as `docker compose`, while v1 was a standalone Python binary. V2 uses hyphens in container names, supports full `condition: service_healthy` dependencies, profiles, `docker compose watch`, and uses BuildKit by default.

Why is my Docker cache mount empty in CI builds?▼

Cache mounts persist only on the build host and are not stored in image layers. Each CI run starts with an empty cache unless you configure BuildKit remote cache export and import between runs.