Non-negotiable rules:
- Read
references/stack.md first to determine the project's base images, registry, and build conventions.
- Then load only the references needed for the actual task.
- Multi-stage builds by default — separate dependency install, build, and production stages.
- Non-root user in production — never run containers as root. Add a user and
USER directive.
- No secrets in images — no
ARG/ENV for passwords, no COPY .env, no secrets in build layers.
- Pin base image versions —
node:22-slim, not node:latest. Use digest pinning for critical images.
.dockerignore is mandatory — exclude node_modules, .git, .env, dist, test artifacts.
- 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:
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
Output Contract
Report:
- which Docker references were loaded
- the build pattern chosen (multi-stage, single, etc.)
- the change made
- the verification run (build success, image size, health check)
1---
2name: docker
3version: 1.1.0
4description: |
5 Write and change container infrastructure the way THIS project already builds and ships it, not
6 by generic defaults — a Docker reference carrying the real conventions for Dockerfiles,
7 multi-stage builds, Compose services, networking, volumes, health checks, registries, BuildKit,
8 security hardening, CI/CD integration, and debugging. Holds the invariants that keep images
9 small and safe: multi-stage builds, non-root runtime, pinned base images, no baked secrets, a
10 mandatory .dockerignore, and frozen lockfiles — so an image lands small, secure, reproducible,
11 and review-ready instead of merely building. Use when a task touches container configuration,
12 images, or deployment infrastructure.
13allowed-tools:
14 - Bash
15 - Read
16 - Write
17 - Edit
18 - Grep
19argument-hint: "[Docker task: Dockerfile, Compose, registry, debugging]"
20arguments:
21 - request
22when_to_use: |
23 Use when the task touches Dockerfiles, docker-compose, container configuration, image builds,
24 registry workflows, or container debugging. Examples: "write a Dockerfile", "optimize this image",
25 "add a service to compose", "debug why the container won't start", "set up multi-stage build",
26 "push to ECR/GCR", "add health checks". Do NOT use for Kubernetes manifests (k8s skill) or for
27 application code that happens to run in containers — it configures the container, not the app.
28effort: high
29metadata:
30 source: https://skillmd.com/skills/ulpi-io/docker
31---
32
33<EXTREMELY-IMPORTANT>
34This skill is a routing shell over the Docker reference set.
35
36Non-negotiable rules:
371. Read `references/stack.md` first to determine the project's base images, registry, and build conventions.
382. Then load only the references needed for the actual task.
393. **Multi-stage builds by default** — separate dependency install, build, and production stages.
404. **Non-root user in production** — never run containers as root. Add a user and `USER` directive.
415. **No secrets in images** — no `ARG`/`ENV` for passwords, no `COPY .env`, no secrets in build layers.
426. **Pin base image versions** — `node:22-slim`, not `node:latest`. Use digest pinning for critical images.
437. **`.dockerignore` is mandatory** — exclude `node_modules`, `.git`, `.env`, `dist`, test artifacts.
448. **Frozen lockfiles in builds** — `--frozen-lockfile` / `--ci` for reproducible installs.
45</EXTREMELY-IMPORTANT>
46
47# docker
48
49## Inputs
50
51- `$request`: The Docker task — Dockerfile, Compose, registry, optimization, or debugging target
52
53## Goal
54
55Route Docker work through proven container patterns so images are small, secure, reproducible, and follow the project's infrastructure conventions.
56
57## Step 0: Read the stack contract
58
59Always start with:
60
61- `references/stack.md`
62
63That establishes: base images, registry, build tool (Docker/BuildKit/Podman), CI integration, and locked conventions.
64
65**Success criteria**: The project's container infrastructure choices are explicit before writing any Dockerfile or Compose config.
66
67## Step 1: Load only the relevant references
68
69Use the routing table to pick reference files. Do not bulk-load the full reference tree.
70
71| Task | Read |
72|------|------|
73| Base images, registry, build conventions, CI | `references/stack.md` |
74| Writing or editing a Dockerfile | `references/dockerfile.md` |
75| Multi-stage builds, layer optimization, caching | `references/multi-stage.md` |
76| docker-compose services, networking, volumes | `references/compose.md` |
77| .dockerignore, build context optimization | `references/build-context.md` |
78| Health checks, readiness, startup probes | `references/health-checks.md` |
79| Security: non-root, read-only FS, capabilities, scanning | `references/security.md` |
80| Image size optimization, distroless, slim, alpine | `references/image-optimization.md` |
81| Registry: push, pull, tagging, ECR/GCR/GHCR/DockerHub | `references/registry.md` |
82| BuildKit features, cache mounts, secret mounts | `references/buildkit.md` |
83| CI/CD: GitHub Actions, GitLab CI, build+push pipelines | `references/ci-cd.md` |
84| Debugging: logs, exec, inspect, networking issues | `references/debugging.md` |
85| Language-specific: Node.js, Python, Go, Rust, Java | `references/language-patterns.md` |
86| Volumes, bind mounts, tmpfs, named volumes | `references/volumes.md` |
87| Networking: bridge, host, overlay, DNS, port mapping | `references/networking.md` |
88
89Multiple tasks? Read multiple files. The references are self-contained.
90
91**Success criteria**: Only the task-relevant Docker conventions are in play.
92
93## Step 2: Implement with the core Docker guardrails
94
95Keep these rules active:
96
97- multi-stage builds: deps → build → production
98- `.dockerignore` excludes everything unnecessary from build context
99- pin base image tags — never `:latest` in production
100- non-root `USER` in the final stage
101- `COPY` only what's needed in each stage — not the entire repo
102- health checks on every long-running service
103- no secrets in `ARG`, `ENV`, or `COPY` — use BuildKit `--mount=type=secret`
104- combine `RUN` commands to minimize layers — but keep readability
105- order layers from least to most frequently changing (deps before code)
106
107**Success criteria**: The container is small, secure, reproducible, and follows the project's conventions.
108
109## Step 3: Verify the build
110
111Use the narrowest relevant verification:
112
113- `docker build` succeeds
114- image size is reasonable for the language/framework
115- container starts and health check passes
116- `.dockerignore` excludes the right files (`docker build --dry-run` or check context size)
117- no secrets visible in `docker history` or `docker inspect`
118
119**Success criteria**: The image builds, runs, and passes basic health validation.
120
121## Guardrails
122
123- Do not inline the whole Docker handbook in `SKILL.md`.
124- Do not skip `references/stack.md`.
125- Do not use `latest` tags for base images in production Dockerfiles.
126- Do not `COPY . .` without a proper `.dockerignore`.
127- Do not run containers as root.
128- Do not put secrets in build args or env vars baked into images.
129- Do not add `disable-model-invocation`; this is a normal domain skill.
130
131## When To Load References
132
133- `references/stack.md`
134 Always.
135
136- then only the task-relevant files under `references/`
137
138## Output Contract
139
140Report:
141
1421. which Docker references were loaded
1432. the build pattern chosen (multi-stage, single, etc.)
1443. the change made
1454. the verification run (build success, image size, health check)