Opinionated Docker workflow that turns bloated Dockerfiles into production-grade…
---name: "docker-development"description: "Use for any Dockerfile or docker-compose file to write, optimize or review, before editing it. Checks layers, caching, size and security with dockerfile_analyzer.py and validates compose files with compose_validator.py."license: MITmetadata: version: 1.0.0 author: Alireza Rezvani category: engineering updated: 2026-03-16--- # 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-development optimize` | Analyze and optimize a Dockerfile for size, speed, and layer caching || `/docker-development compose` | Generate or improve docker-compose.yml with best practices || `/docker-development 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-development optimize` — Dockerfile Optimization 1. **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 2. **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 ``` 3. **Generate optimized Dockerfile** - Apply all relevant optimizations - Add inline comments explaining each decision - Report estimated size reduction 4. **Validate** ```bash python3 scripts/dockerfile_analyzer.py Dockerfile ``` ### `/docker-development compose` — Docker Compose Configuration 1. **Identify services** - Application (web, API, worker) - Database (postgres, mysql, redis, mongo) - Cache (redis, memcached) - Queue (rabbitmq, kafka) - Reverse proxy (nginx, traefik, caddy) 2. **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 ``` 3. **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-development security` — Container Security Audit 1. **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 | 2. **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 | 3. **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:**```bash# Analyze a Dockerfilepython3 scripts/dockerfile_analyzer.py Dockerfile # JSON outputpython3 scripts/dockerfile_analyzer.py Dockerfile --output json # Analyze with security focuspython3 scripts/dockerfile_analyzer.py Dockerfile --security # Check a specific directorypython3 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:**```bash# Validate a compose filepython3 scripts/compose_validator.py docker-compose.yml # JSON outputpython3 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++) ```dockerfile# Build stageFROM golang:1.22-alpine AS builderWORKDIR /appCOPY go.mod go.sum ./RUN go mod downloadCOPY . .RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server # Runtime stageFROM gcr.io/distroless/static-debian12COPY --from=builder /app/server /serverUSER nonroot:nonrootENTRYPOINT ["/server"]``` ### Pattern 2: Node.js / TypeScript ```dockerfile# Dependencies stageFROM node:20-alpine AS depsWORKDIR /appCOPY package.json package-lock.json ./RUN npm ci --production=false # Build stageFROM deps AS builderCOPY . .RUN npm run build # Runtime stageFROM node:20-alpineWORKDIR /appRUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001COPY --from=builder /app/dist ./distCOPY --from=deps /app/node_modules ./node_modulesCOPY package.json ./USER appuserEXPOSE 3000CMD ["node", "dist/index.js"]``` ### Pattern 3: Python ```dockerfile# Build stageFROM python:3.12-slim AS builderWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir --prefix=/install -r requirements.txt # Runtime stageFROM python:3.12-slimWORKDIR /appRUN groupadd -r appgroup && useradd -r -g appgroup appuserCOPY --from=builder /install /usr/localCOPY . .USER appuserEXPOSE 8000CMD ["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)```bashgit clone https://github.com/alirezarezvani/claude-skills.gitcp -r claude-skills/engineering/docker-development ~/.claude/skills/``` ### Multi-tool install```bash./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw``` ### OpenClaw```bashclawhub 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. ## More in this skill Load these only when the task needs them. - [references/compose-patterns.md](references/compose-patterns.md) — Docker Compose Patterns Reference- [references/dockerfile-best-practices.md](references/dockerfile-best-practices.md) — Dockerfile Best Practices Reference