Docker Development
Smaller images. Faster builds. Secure containers. No guesswork.
Opinionated Docker workflow that turns bloated Dockerfiles into production-grade containers. Covers optimization, multi-stage builds, compose orchestration, and security hardening.
Not a Docker tutorial — a set of concrete decisions about how to build containers that don't waste time, space, or attack surface.
Slash Commands
| Command |
What it does |
/docker:optimize |
Analyze and optimize a Dockerfile for size, speed, and layer caching |
/docker:compose |
Generate or improve docker-compose.yml with best practices |
/docker:security |
Audit a Dockerfile or running container for security issues |
When This Skill Activates
Recognize these patterns from the user:
- "Optimize this Dockerfile"
- "My Docker build is slow"
- "Create a docker-compose for this project"
- "Is this Dockerfile secure?"
- "Reduce my Docker image size"
- "Set up multi-stage builds"
- "Docker best practices for [language/framework]"
- Any request involving: Dockerfile, docker-compose, container, image size, build cache, Docker security
If the user has a Dockerfile or wants to containerize something → this skill applies.
Workflow
/docker:optimize — Dockerfile Optimization
Analyze current state
- Read the Dockerfile
- Identify base image and its size
- Count layers (each RUN/COPY/ADD = 1 layer)
- Check for common anti-patterns
Apply optimization checklist
BASE IMAGE
├── Use specific tags, never :latest in production
├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)
├── Pin digest for reproducibility in CI: image@sha256:...
└── Match base to runtime needs (don't use python:3.12 for a compiled binary)
LAYER OPTIMIZATION
├── Combine related RUN commands with && \
├── Order layers: least-changing first (deps before source code)
├── Clean package manager cache in the same RUN layer
├── Use .dockerignore to exclude unnecessary files
└── Separate build deps from runtime deps
BUILD CACHE
├── COPY dependency files before source code (package.json, requirements.txt, go.mod)
├── Install deps in a separate layer from code copy
├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache
└── Avoid COPY . . before dependency installation
MULTI-STAGE BUILDS
├── Stage 1: build (full SDK, build tools, dev deps)
├── Stage 2: runtime (minimal base, only production artifacts)
├── COPY --from=builder only what's needed
└── Final image should have NO build tools, NO source code, NO dev deps
Generate optimized Dockerfile
- Apply all relevant optimizations
- Add inline comments explaining each decision
- Report estimated size reduction
Validate
python3 scripts/dockerfile_analyzer.py Dockerfile
/docker:compose — Docker Compose Configuration
Identify services
- Application (web, API, worker)
- Database (postgres, mysql, redis, mongo)
- Cache (redis, memcached)
- Queue (rabbitmq, kafka)
- Reverse proxy (nginx, traefik, caddy)
Apply compose best practices
SERVICES
├── Use depends_on with condition: service_healthy
├── Add healthchecks for every service
├── Set resource limits (mem_limit, cpus)
├── Use named volumes for persistent data
└── Pin image versions
NETWORKING
├── Create explicit networks (don't rely on default)
├── Separate frontend and backend networks
├── Only expose ports that need external access
└── Use internal: true for backend-only networks
ENVIRONMENT
├── Use env_file for secrets, not inline environment
├── Never commit .env files (add to .gitignore)
├── Use variable substitution: ${VAR:-default}
└── Document all required env vars
DEVELOPMENT vs PRODUCTION
├── Use compose profiles or override files
├── Dev: bind mounts for hot reload, debug ports exposed
├── Prod: named volumes, no debug ports, restart: unless-stopped
└── docker-compose.override.yml for dev-only config
Generate compose file
- Output docker-compose.yml with healthchecks, networks, volumes
- Generate .env.example with all required variables documented
- Add dev/prod profile annotations
/docker:security — Container Security Audit
Dockerfile audit
| Check |
Severity |
Fix |
| Running as root |
Critical |
Add USER nonroot after creating user |
| Using :latest tag |
High |
Pin to specific version |
| Secrets in ENV/ARG |
Critical |
Use BuildKit secrets: --mount=type=secret |
| COPY with broad glob |
Medium |
Use specific paths, add .dockerignore |
| Unnecessary EXPOSE |
Low |
Only expose ports the app uses |
| No HEALTHCHECK |
Medium |
Add HEALTHCHECK with appropriate interval |
| Privileged instructions |
High |
Avoid --privileged, drop capabilities |
| Package manager cache retained |
Low |
Clean in same RUN layer |
Runtime security checks
| Check |
Severity |
Fix |
| Container running as root |
Critical |
Set user in Dockerfile or compose |
| Writable root filesystem |
Medium |
Use read_only: true in compose |
| All capabilities retained |
High |
Drop all, add only needed: cap_drop: [ALL] |
| No resource limits |
Medium |
Set mem_limit and cpus |
| Host network mode |
High |
Use bridge or custom network |
| Sensitive mounts |
Critical |
Never mount /etc, /var/run/docker.sock in prod |
| No log driver configured |
Low |
Set logging: with size limits |
Generate security report
SECURITY AUDIT — [Dockerfile/Image name]
Date: [timestamp]
CRITICAL: [count]
HIGH: [count]
MEDIUM: [count]
LOW: [count]
[Detailed findings with fix recommendations]
Tooling
scripts/dockerfile_analyzer.py
CLI utility for static analysis of Dockerfiles.
Features:
- Layer count and optimization suggestions
- Base image analysis with size estimates
- Anti-pattern detection (15+ rules)
- Security issue flagging
- Multi-stage build detection and validation
- JSON and text output
Usage:
# Analyze a Dockerfile
python3 scripts/dockerfile_analyzer.py Dockerfile
# JSON output
python3 scripts/dockerfile_analyzer.py Dockerfile --output json
# Analyze with security focus
python3 scripts/dockerfile_analyzer.py Dockerfile --security
# Check a specific directory
python3 scripts/dockerfile_analyzer.py path/to/Dockerfile
scripts/compose_validator.py
CLI utility for validating docker-compose files.
Features:
- Service dependency validation
- Healthcheck presence detection
- Network configuration analysis
- Volume mount validation
- Environment variable audit
- Port conflict detection
- Best practice scoring
Usage:
# Validate a compose file
python3 scripts/compose_validator.py docker-compose.yml
# JSON output
python3 scripts/compose_validator.py docker-compose.yml --output json
# Strict mode (fail on warnings)
python3 scripts/compose_validator.py docker-compose.yml --strict
Multi-Stage Build Patterns
Pattern 1: Compiled Language (Go, Rust, C++)
# Build stage
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server
# Runtime stage
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]
Pattern 2: Node.js / TypeScript
# Dependencies stage
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false
# Build stage
FROM deps AS builder
COPY . .
RUN npm run build
# Runtime stage
FROM node:20-alpine
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
COPY --from=builder /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]
Pattern 3: Python
# Build stage
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
# Runtime stage
FROM python:3.12-slim
WORKDIR /app
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
COPY --from=builder /install /usr/local
COPY . .
USER appuser
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Base Image Decision Tree
Is it a compiled binary (Go, Rust, C)?
├── Yes → distroless/static or scratch
└── No
├── Need a shell for debugging?
│ ├── Yes → alpine variant (e.g., node:20-alpine)
│ └── No → distroless variant
├── Need glibc (not musl)?
│ ├── Yes → slim variant (e.g., python:3.12-slim)
│ └── No → alpine variant
└── Need specific OS packages?
├── Many → debian-slim
└── Few → alpine + apk add
Proactive Triggers
Flag these without being asked:
- Dockerfile uses :latest → Suggest pinning to a specific version tag.
- No .dockerignore → Create one. At minimum:
.git, node_modules, __pycache__, .env.
- COPY . . before dependency install → Cache bust. Reorder to install deps first.
- Running as root → Add USER instruction. No exceptions for production.
- Secrets in ENV or ARG → Use BuildKit secret mounts. Never bake secrets into layers.
- Image over 1GB → Multi-stage build required. No reason for a production image this large.
- No healthcheck → Add one. Orchestrators (Compose, K8s) need it for proper lifecycle management.
- apt-get without cleanup in same layer →
rm -rf /var/lib/apt/lists/* in the same RUN.
Installation
One-liner (any tool)
git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/docker-development ~/.claude/skills/
Multi-tool install
./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw
OpenClaw
clawhub install cs-docker-development
Related Skills
- senior-devops — Broader DevOps scope (CI/CD, IaC, monitoring). Complementary — use docker-development for container-specific work, senior-devops for pipeline and infrastructure.
- senior-security — Application security. Complementary — docker-development covers container security, senior-security covers application-level threats.
- autoresearch-agent — Can optimize Docker build times or image sizes as measurable experiments.
- ci-cd-pipeline-builder — Pipeline construction. Complementary — docker-development builds the containers, ci-cd-pipeline-builder deploys them.
1---2name: docker-development3description: "Docker and container development agent skill and plugin for Dockerfile optimization, docker-compose orchestration, multi-stage builds, and container security hardening. Use when: user wants to optimize a Dockerfile, create or improve docker-compose configurations, implement multi-stage builds, audit container security, reduce image size, or follow container best practices. Covers build performance, layer caching, secret management, and production-ready container patterns."4license: MIT5metadata:6 source: https://skillmd.com/skills/bestagentkits/docker-development7 version: 1.0.08 author: Alireza Rezvani9 category: engineering10 updated: 2026-03-1611---1213# Docker Development1415> Smaller images. Faster builds. Secure containers. No guesswork.1617Opinionated Docker workflow that turns bloated Dockerfiles into production-grade containers. Covers optimization, multi-stage builds, compose orchestration, and security hardening.1819Not a Docker tutorial — a set of concrete decisions about how to build containers that don't waste time, space, or attack surface.2021---2223## Slash Commands2425| Command | What it does |26|---------|-------------|27| `/docker:optimize` | Analyze and optimize a Dockerfile for size, speed, and layer caching |28| `/docker:compose` | Generate or improve docker-compose.yml with best practices |29| `/docker:security` | Audit a Dockerfile or running container for security issues |3031---3233## When This Skill Activates3435Recognize these patterns from the user:3637- "Optimize this Dockerfile"38- "My Docker build is slow"39- "Create a docker-compose for this project"40- "Is this Dockerfile secure?"41- "Reduce my Docker image size"42- "Set up multi-stage builds"43- "Docker best practices for [language/framework]"44- Any request involving: Dockerfile, docker-compose, container, image size, build cache, Docker security4546If the user has a Dockerfile or wants to containerize something → this skill applies.4748---4950## Workflow5152### `/docker:optimize` — Dockerfile Optimization53541. **Analyze current state**55 - Read the Dockerfile56 - Identify base image and its size57 - Count layers (each RUN/COPY/ADD = 1 layer)58 - Check for common anti-patterns59602. **Apply optimization checklist**6162 ```63 BASE IMAGE64 ├── Use specific tags, never :latest in production65 ├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)66 ├── Pin digest for reproducibility in CI: image@sha256:...67 └── Match base to runtime needs (don't use python:3.12 for a compiled binary)6869 LAYER OPTIMIZATION70 ├── Combine related RUN commands with && \71 ├── Order layers: least-changing first (deps before source code)72 ├── Clean package manager cache in the same RUN layer73 ├── Use .dockerignore to exclude unnecessary files74 └── Separate build deps from runtime deps7576 BUILD CACHE77 ├── COPY dependency files before source code (package.json, requirements.txt, go.mod)78 ├── Install deps in a separate layer from code copy79 ├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache80 └── Avoid COPY . . before dependency installation8182 MULTI-STAGE BUILDS83 ├── Stage 1: build (full SDK, build tools, dev deps)84 ├── Stage 2: runtime (minimal base, only production artifacts)85 ├── COPY --from=builder only what's needed86 └── Final image should have NO build tools, NO source code, NO dev deps87 ```88893. **Generate optimized Dockerfile**90 - Apply all relevant optimizations91 - Add inline comments explaining each decision92 - Report estimated size reduction93944. **Validate**95 ```bash96 python3 scripts/dockerfile_analyzer.py Dockerfile97 ```9899### `/docker:compose` — Docker Compose Configuration1001011. **Identify services**102 - Application (web, API, worker)103 - Database (postgres, mysql, redis, mongo)104 - Cache (redis, memcached)105 - Queue (rabbitmq, kafka)106 - Reverse proxy (nginx, traefik, caddy)1071082. **Apply compose best practices**109110 ```111 SERVICES112 ├── Use depends_on with condition: service_healthy113 ├── Add healthchecks for every service114 ├── Set resource limits (mem_limit, cpus)115 ├── Use named volumes for persistent data116 └── Pin image versions117118 NETWORKING119 ├── Create explicit networks (don't rely on default)120 ├── Separate frontend and backend networks121 ├── Only expose ports that need external access122 └── Use internal: true for backend-only networks123124 ENVIRONMENT125 ├── Use env_file for secrets, not inline environment126 ├── Never commit .env files (add to .gitignore)127 ├── Use variable substitution: ${VAR:-default}128 └── Document all required env vars129130 DEVELOPMENT vs PRODUCTION131 ├── Use compose profiles or override files132 ├── Dev: bind mounts for hot reload, debug ports exposed133 ├── Prod: named volumes, no debug ports, restart: unless-stopped134 └── docker-compose.override.yml for dev-only config135 ```1361373. **Generate compose file**138 - Output docker-compose.yml with healthchecks, networks, volumes139 - Generate .env.example with all required variables documented140 - Add dev/prod profile annotations141142### `/docker:security` — Container Security Audit1431441. **Dockerfile audit**145146 | Check | Severity | Fix |147 |-------|----------|-----|148 | Running as root | Critical | Add `USER nonroot` after creating user |149 | Using :latest tag | High | Pin to specific version |150 | Secrets in ENV/ARG | Critical | Use BuildKit secrets: `--mount=type=secret` |151 | COPY with broad glob | Medium | Use specific paths, add .dockerignore |152 | Unnecessary EXPOSE | Low | Only expose ports the app uses |153 | No HEALTHCHECK | Medium | Add HEALTHCHECK with appropriate interval |154 | Privileged instructions | High | Avoid `--privileged`, drop capabilities |155 | Package manager cache retained | Low | Clean in same RUN layer |1561572. **Runtime security checks**158159 | Check | Severity | Fix |160 |-------|----------|-----|161 | Container running as root | Critical | Set user in Dockerfile or compose |162 | Writable root filesystem | Medium | Use `read_only: true` in compose |163 | All capabilities retained | High | Drop all, add only needed: `cap_drop: [ALL]` |164 | No resource limits | Medium | Set `mem_limit` and `cpus` |165 | Host network mode | High | Use bridge or custom network |166 | Sensitive mounts | Critical | Never mount /etc, /var/run/docker.sock in prod |167 | No log driver configured | Low | Set `logging:` with size limits |1681693. **Generate security report**170 ```171 SECURITY AUDIT — [Dockerfile/Image name]172 Date: [timestamp]173174 CRITICAL: [count]175 HIGH: [count]176 MEDIUM: [count]177 LOW: [count]178179 [Detailed findings with fix recommendations]180 ```181182---183184## Tooling185186### `scripts/dockerfile_analyzer.py`187188CLI utility for static analysis of Dockerfiles.189190**Features:**191- Layer count and optimization suggestions192- Base image analysis with size estimates193- Anti-pattern detection (15+ rules)194- Security issue flagging195- Multi-stage build detection and validation196- JSON and text output197198**Usage:**199```bash200# Analyze a Dockerfile201python3 scripts/dockerfile_analyzer.py Dockerfile202203# JSON output204python3 scripts/dockerfile_analyzer.py Dockerfile --output json205206# Analyze with security focus207python3 scripts/dockerfile_analyzer.py Dockerfile --security208209# Check a specific directory210python3 scripts/dockerfile_analyzer.py path/to/Dockerfile211```212213### `scripts/compose_validator.py`214215CLI utility for validating docker-compose files.216217**Features:**218- Service dependency validation219- Healthcheck presence detection220- Network configuration analysis221- Volume mount validation222- Environment variable audit223- Port conflict detection224- Best practice scoring225226**Usage:**227```bash228# Validate a compose file229python3 scripts/compose_validator.py docker-compose.yml230231# JSON output232python3 scripts/compose_validator.py docker-compose.yml --output json233234# Strict mode (fail on warnings)235python3 scripts/compose_validator.py docker-compose.yml --strict236```237238---239240## Multi-Stage Build Patterns241242### Pattern 1: Compiled Language (Go, Rust, C++)243244```dockerfile245# Build stage246FROM golang:1.22-alpine AS builder247WORKDIR /app248COPY go.mod go.sum ./249RUN go mod download250COPY . .251RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server252253# Runtime stage254FROM gcr.io/distroless/static-debian12255COPY --from=builder /app/server /server256USER nonroot:nonroot257ENTRYPOINT ["/server"]258```259260### Pattern 2: Node.js / TypeScript261262```dockerfile263# Dependencies stage264FROM node:20-alpine AS deps265WORKDIR /app266COPY package.json package-lock.json ./267RUN npm ci --production=false268269# Build stage270FROM deps AS builder271COPY . .272RUN npm run build273274# Runtime stage275FROM node:20-alpine276WORKDIR /app277RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001278COPY --from=builder /app/dist ./dist279COPY --from=deps /app/node_modules ./node_modules280COPY package.json ./281USER appuser282EXPOSE 3000283CMD ["node", "dist/index.js"]284```285286### Pattern 3: Python287288```dockerfile289# Build stage290FROM python:3.12-slim AS builder291WORKDIR /app292COPY requirements.txt .293RUN pip install --no-cache-dir --prefix=/install -r requirements.txt294295# Runtime stage296FROM python:3.12-slim297WORKDIR /app298RUN groupadd -r appgroup && useradd -r -g appgroup appuser299COPY --from=builder /install /usr/local300COPY . .301USER appuser302EXPOSE 8000303CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]304```305306---307308## Base Image Decision Tree309310```311Is it a compiled binary (Go, Rust, C)?312├── Yes → distroless/static or scratch313└── No314 ├── Need a shell for debugging?315 │ ├── Yes → alpine variant (e.g., node:20-alpine)316 │ └── No → distroless variant317 ├── Need glibc (not musl)?318 │ ├── Yes → slim variant (e.g., python:3.12-slim)319 │ └── No → alpine variant320 └── Need specific OS packages?321 ├── Many → debian-slim322 └── Few → alpine + apk add323```324325---326327## Proactive Triggers328329Flag these without being asked:330331- **Dockerfile uses :latest** → Suggest pinning to a specific version tag.332- **No .dockerignore** → Create one. At minimum: `.git`, `node_modules`, `__pycache__`, `.env`.333- **COPY . . before dependency install** → Cache bust. Reorder to install deps first.334- **Running as root** → Add USER instruction. No exceptions for production.335- **Secrets in ENV or ARG** → Use BuildKit secret mounts. Never bake secrets into layers.336- **Image over 1GB** → Multi-stage build required. No reason for a production image this large.337- **No healthcheck** → Add one. Orchestrators (Compose, K8s) need it for proper lifecycle management.338- **apt-get without cleanup in same layer** → `rm -rf /var/lib/apt/lists/*` in the same RUN.339340---341342## Installation343344### One-liner (any tool)345```bash346git clone https://github.com/alirezarezvani/claude-skills.git347cp -r claude-skills/engineering/docker-development ~/.claude/skills/348```349350### Multi-tool install351```bash352./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw353```354355### OpenClaw356```bash357clawhub install cs-docker-development358```359360---361362## Related Skills363364- **senior-devops** — Broader DevOps scope (CI/CD, IaC, monitoring). Complementary — use docker-development for container-specific work, senior-devops for pipeline and infrastructure.365- **senior-security** — Application security. Complementary — docker-development covers container security, senior-security covers application-level threats.366- **autoresearch-agent** — Can optimize Docker build times or image sizes as measurable experiments.367- **ci-cd-pipeline-builder** — Pipeline construction. Complementary — docker-development builds the containers, ci-cd-pipeline-builder deploys them.