name: docker description: > Comprehensive Docker workflow and diagnostics guidance for all environments (Linux, macOS, Windows Docker Desktop with WSL2 backend). Use when the agent needs to build, run, debug, or troubleshoot containers; author Dockerfiles or compose.yaml files; manage images and registries; configure networking or volumes/storage; work with Buildx/Bake, Scout/SBOM/security, Swarm orchestration, Docker Desktop contexts, or Docker AI tooling (docker ai, docker agent, mcp, model, sandbox, offload). Trigger whenever the user mentions docker, containers, containerizing an app, Dockerfile, compose, image registry, "run this in Docker", "dockerize my app", or asks about container networking, volumes, or any docker subcommand — even if they don't explicitly say "skill". Also trigger for Docker security scanning or AI model serving via Docker Model Runner.

Docker

Use this skill to keep Docker work deterministic, safe, and fast across Linux, macOS, and Windows Docker Desktop hosts.

Quick Start

1. Run scripts/probe-docker.ps1 (Windows) or docker info / docker version (Linux/macOS) first for environment truth.
2. Choose the smallest workflow that solves the request:
   • Core container/build/compose workflow in this file covers ~80% of tasks.
   • Load a reference file only when you need depth on a specific domain.
   • Reuse assets/templates/ starter packs before writing boilerplate from scratch.
3. Default to read-only diagnostics before proposing mutating commands.
4. Confirm before destructive commands (rm, prune, down -v, sandbox reset, builder/cache deletion).
5. Prefer installed CLI behavior when docs and runtime diverge; note the caveat with concrete versions.

Intent Router (Progressive Disclosure)

Load only the reference file needed for the active request.

• references/install-and-setup.md — Installing Docker Desktop (macOS/Windows) or Docker Engine (Linux), and post-install configuration.
• references/core.md — Windows Desktop-first diagnostics, context management, Desktop status.
• references/containers.md — run/exec/logs/inspect/debug/stats and crash triage.
• references/images.md — Dockerfile authoring, multi-stage patterns, Buildx/Bake.
• references/compose.md — Compose authoring and service orchestration.
• references/networking.md — bridge/overlay/macvlan, DNS, port publishing.
• references/volumes.md — named volumes, bind mounts, backup/restore patterns.
• references/registry.md — login/tag/push/pull and registry hygiene.
• references/swarm.md — swarm init, services, stacks, safe operations.
• references/troubleshooting.md — systematic debugging and error classification.
• references/security.md — Scout, SBOM, DHI, pass secrets, supply chain checks.
• references/ai-and-agents.md — Docker AI, agent/cagent, MCP toolkit, model runner, sandbox.
• references/cloud-and-remote.md — Offload, Build Cloud, remote builders and contexts.

Quick Command Reference

These cover ~80% of daily Docker use. Use them directly without loading a reference file.

# Container lifecycle
docker run -d --name myapp -p 8080:80 nginx          # Run detached with port mapping
docker run -it --rm ubuntu bash                       # Interactive, auto-remove on exit
docker ps                                             # List running containers
docker ps -a                                          # All containers (incl. stopped)
docker stop myapp && docker rm myapp                  # Stop and remove
docker logs myapp -f                                  # Follow logs
docker logs myapp --tail=100                          # Last 100 lines
docker exec -it myapp bash                            # Shell into running container
docker inspect myapp                                  # Full metadata (JSON)
docker stats                                          # Live resource usage

# Images
docker build -t myapp:latest .                        # Build from Dockerfile in cwd
docker pull nginx:alpine                              # Pull image
docker images                                         # List local images
docker rmi myapp:latest                               # Remove image
docker tag myapp:latest myregistry/myapp:v1.2         # Tag for push

# Compose (v2 — no hyphen)
docker compose config                                 # Validate and view merged config
docker compose up -d                                  # Start all services detached
docker compose down                                   # Stop and remove containers+networks
docker compose logs -f api                            # Follow logs for one service
docker compose exec api sh                            # Shell into service container
docker compose ps                                     # Service status
docker compose build --no-cache                       # Rebuild all images

# Buildx / multi-platform
docker buildx ls
docker buildx build --platform linux/amd64,linux/arm64 -t myorg/myapp:v1 --push .

# System
docker system df                                      # Disk usage breakdown
docker system prune                                   # Remove unused objects (see safety)

Safety Matrix

Writing Dockerfiles

When asked to write a Dockerfile, always apply these best practices by default:

• Layer order — put things that change least at the top (base image, system deps), most at the bottom (app code). Maximizes cache reuse.
• Multi-stage builds — compile/install in a build stage; copy only artifacts to a minimal runtime image.
• Non-root user — create and switch to a non-root user before CMD.
• Minimal base image — prefer alpine, distroless, or slim. Use full images only when system packages are needed.
• Combine RUN commands — chain related commands with &&; clean up package caches in the same layer.
• Always create .dockerignore alongside Dockerfile.

For complete Dockerfile templates (Node.js, Python, Go) and .dockerignore patterns, see references/images.md.

Docker Compose Authoring

Key patterns for compose files:

• Use condition: service_healthy on depends_on when the dependency has a healthcheck.
• Always define named volumes rather than bare bind mounts for data you care about.
• Scope services to internal-only networks when they don't need external access.
• Use restart: unless-stopped for production; omit for dev tooling containers.
• Set an explicit name: at the top to avoid directory-name collisions.

For complete compose file templates with health checks, see references/compose.md.

Diagnostic Workflow

When a container is crashing or misbehaving:

docker ps -a                              # Find container and exit code
docker logs <name> --tail=100             # Last 100 lines (stderr included with 2>&1)
docker inspect <name>                     # Full JSON — check State, Config, Mounts
docker stats --no-stream                  # Snapshot of memory/CPU (check for OOM)
docker exec -it <name> sh                 # Shell in (if still running)
docker debug <name>                       # Debug sidecar, works on stopped containers
docker compose ps && docker compose logs --tail=50   # Compose: all services at once

Exit codes: 0 = clean exit, 1 = app error, 137 = OOM killed, 139 = segfault, 143 = SIGTERM, 125/126/127 = Docker/exec errors.

Core Workflow (Windows Desktop)

1. Establish baseline — Run scripts/probe-docker.ps1 -Json for structured diagnostics (CLI version, context, plugin availability, daemon reachability).
2. Diagnose before changing state — Run scripts/doctor-docker.ps1 for actionable checks. Use -Quick for fast triage; -IncludeScout / -IncludeOffload only when in scope.
3. Execute scoped operations — container lifecycle, build pipeline, compose orchestration, context/Desktop checks.
4. Report findings by root cause — sandbox/host permission boundary, daemon/service state, config mismatch.

Resource Index

• scripts/probe-docker.ps1 — probe-docker.ps1 [-Json] [-IncludeExperimental] — read-only host/runtime probe.
• scripts/doctor-docker.ps1 — doctor-docker.ps1 [-Quick] [-IncludeOffload] [-IncludeScout] — diagnostics and recommendations.
• assets/templates/ — reusable starter packs for minimal service, compose stack, and multi-arch Buildx.
• references/*.md — deep domain coverage (see Intent Router above).