Skill.md
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.
SKILL.md
---
name: "docker-development"
description: "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."
license: MIT
metadata:
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: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
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
docker buildx build --progress=plain --no-cache .
docker image inspect <image-name>:<tag> --format '{{.Size}}'
```
### `/docker: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: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]
```
---
## Manual Validation
This public skill does not bundle analyzer scripts. Validate Docker changes with Docker itself, optional standard linters if already available in the repo, and the checklists in `references/`.
### Dockerfile validation checklist
- Build succeeds with BuildKit enabled.
- `docker history` shows dependency layers before source layers.
- Final image contains only runtime artifacts.
- Final image runs as a non-root user.
- Package manager caches are removed in the same layer where they are created.
- Secrets are not present in `ENV`, `ARG`, layers, build logs, or image history.
- Image size and layer count are recorded before and after the change.
```bash
docker buildx build --progress=plain -t app:optimized .
docker history app:optimized
docker image inspect app:optimized --format '{{.Size}}'
```
### Compose validation checklist
- `docker compose config` renders successfully.
- Every long-running service has a healthcheck.
- Only public services publish ports to the host.
- Backend-only services use internal networks.
- Persistent data uses named volumes.
- Resource limits and restart policy match the environment.
- Secrets come from files, secret stores, or external env injection, not committed literals.
```bash
docker compose config
docker compose up --build
docker compose ps
```
---
## Multi-Stage Build Patterns
### Pattern 1: Compiled Language (Go, Rust, C++)
```dockerfile
# 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
```dockerfile
# 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
```dockerfile
# 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.
---
## 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.
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.