docker-development

# 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
   python3 scripts/dockerfile_analyzer.py Dockerfile
   ```

### `/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]
   ```

---

## 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 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:**
```bash
# 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++)

```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.

---

## Installation

### One-liner (any tool)
```bash
git clone https://github.com/alirezarezvani/claude-skills.git
cp -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
```bash
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.

{
  "format": "aiskill/v1",
  "skill": {
    "name": "docker-development",
    "slug": "docker-development",
    "version": "1.0.0",
    "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.",
    "category": "Development",
    "tags": [
      "engineering",
      "devops",
      "security",
      "agents",
      "performance"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Docker Development\r\n\r\n> Smaller images. Faster builds. Secure containers. No guesswork.\r\n\r\nOpinionated Docker workflow that turns bloated Dockerfiles into production-grade containers. Covers optimization, multi-stage builds, compose orchestration, and security hardening.\r\n\r\nNot a Docker tutorial — a set of concrete decisions about how to build containers that don't waste time, space, or attack surface.\r\n\r\n---\r\n\r\n## Slash Commands\r\n\r\n| Command | What it does |\r\n|---------|-------------|\r\n| `/docker:optimize` | Analyze and optimize a Dockerfile for size, speed, and layer caching |\r\n| `/docker:compose` | Generate or improve docker-compose.yml with best practices |\r\n| `/docker:security` | Audit a Dockerfile or running container for security issues |\r\n\r\n---\r\n\r\n## When This Skill Activates\r\n\r\nRecognize these patterns from the user:\r\n\r\n- \"Optimize this Dockerfile\"\r\n- \"My Docker build is slow\"\r\n- \"Create a docker-compose for this project\"\r\n- \"Is this Dockerfile secure?\"\r\n- \"Reduce my Docker image size\"\r\n- \"Set up multi-stage builds\"\r\n- \"Docker best practices for [language/framework]\"\r\n- Any request involving: Dockerfile, docker-compose, container, image size, build cache, Docker security\r\n\r\nIf the user has a Dockerfile or wants to containerize something → this skill applies.\r\n\r\n---\r\n\r\n## Workflow\r\n\r\n### `/docker:optimize` — Dockerfile Optimization\r\n\r\n1. **Analyze current state**\r\n   - Read the Dockerfile\r\n   - Identify base image and its size\r\n   - Count layers (each RUN/COPY/ADD = 1 layer)\r\n   - Check for common anti-patterns\r\n\r\n2. **Apply optimization checklist**\r\n\r\n   ```\r\n   BASE IMAGE\r\n   ├── Use specific tags, never :latest in production\r\n   ├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)\r\n   ├── Pin digest for reproducibility in CI: image@sha256:...\r\n   └── Match base to runtime needs (don't use python:3.12 for a compiled binary)\r\n\r\n   LAYER OPTIMIZATION\r\n   ├── Combine related RUN commands with && \\\r\n   ├── Order layers: least-changing first (deps before source code)\r\n   ├── Clean package manager cache in the same RUN layer\r\n   ├── Use .dockerignore to exclude unnecessary files\r\n   └── Separate build deps from runtime deps\r\n\r\n   BUILD CACHE\r\n   ├── COPY dependency files before source code (package.json, requirements.txt, go.mod)\r\n   ├── Install deps in a separate layer from code copy\r\n   ├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache\r\n   └── Avoid COPY . . before dependency installation\r\n\r\n   MULTI-STAGE BUILDS\r\n   ├── Stage 1: build (full SDK, build tools, dev deps)\r\n   ├── Stage 2: runtime (minimal base, only production artifacts)\r\n   ├── COPY --from=builder only what's needed\r\n   └── Final image should have NO build tools, NO source code, NO dev deps\r\n   ```\r\n\r\n3. **Generate optimized Dockerfile**\r\n   - Apply all relevant optimizations\r\n   - Add inline comments explaining each decision\r\n   - Report estimated size reduction\r\n\r\n4. **Validate**\r\n   ```bash\r\n   python3 scripts/dockerfile_analyzer.py Dockerfile\r\n   ```\r\n\r\n### `/docker:compose` — Docker Compose Configuration\r\n\r\n1. **Identify services**\r\n   - Application (web, API, worker)\r\n   - Database (postgres, mysql, redis, mongo)\r\n   - Cache (redis, memcached)\r\n   - Queue (rabbitmq, kafka)\r\n   - Reverse proxy (nginx, traefik, caddy)\r\n\r\n2. **Apply compose best practices**\r\n\r\n   ```\r\n   SERVICES\r\n   ├── Use depends_on with condition: service_healthy\r\n   ├── Add healthchecks for every service\r\n   ├── Set resource limits (mem_limit, cpus)\r\n   ├── Use named volumes for persistent data\r\n   └── Pin image versions\r\n\r\n   NETWORKING\r\n   ├── Create explicit networks (don't rely on default)\r\n   ├── Separate frontend and backend networks\r\n   ├── Only expose ports that need external access\r\n   └── Use internal: true for backend-only networks\r\n\r\n   ENVIRONMENT\r\n   ├── Use env_file for secrets, not inline environment\r\n   ├── Never commit .env files (add to .gitignore)\r\n   ├── Use variable substitution: ${VAR:-default}\r\n   └── Document all required env vars\r\n\r\n   DEVELOPMENT vs PRODUCTION\r\n   ├── Use compose profiles or override files\r\n   ├── Dev: bind mounts for hot reload, debug ports exposed\r\n   ├── Prod: named volumes, no debug ports, restart: unless-stopped\r\n   └── docker-compose.override.yml for dev-only config\r\n   ```\r\n\r\n3. **Generate compose file**\r\n   - Output docker-compose.yml with healthchecks, networks, volumes\r\n   - Generate .env.example with all required variables documented\r\n   - Add dev/prod profile annotations\r\n\r\n### `/docker:security` — Container Security Audit\r\n\r\n1. **Dockerfile audit**\r\n\r\n   | Check | Severity | Fix |\r\n   |-------|----------|-----|\r\n   | Running as root | Critical | Add `USER nonroot` after creating user |\r\n   | Using :latest tag | High | Pin to specific version |\r\n   | Secrets in ENV/ARG | Critical | Use BuildKit secrets: `--mount=type=secret` |\r\n   | COPY with broad glob | Medium | Use specific paths, add .dockerignore |\r\n   | Unnecessary EXPOSE | Low | Only expose ports the app uses |\r\n   | No HEALTHCHECK | Medium | Add HEALTHCHECK with appropriate interval |\r\n   | Privileged instructions | High | Avoid `--privileged`, drop capabilities |\r\n   | Package manager cache retained | Low | Clean in same RUN layer |\r\n\r\n2. **Runtime security checks**\r\n\r\n   | Check | Severity | Fix |\r\n   |-------|----------|-----|\r\n   | Container running as root | Critical | Set user in Dockerfile or compose |\r\n   | Writable root filesystem | Medium | Use `read_only: true` in compose |\r\n   | All capabilities retained | High | Drop all, add only needed: `cap_drop: [ALL]` |\r\n   | No resource limits | Medium | Set `mem_limit` and `cpus` |\r\n   | Host network mode | High | Use bridge or custom network |\r\n   | Sensitive mounts | Critical | Never mount /etc, /var/run/docker.sock in prod |\r\n   | No log driver configured | Low | Set `logging:` with size limits |\r\n\r\n3. **Generate security report**\r\n   ```\r\n   SECURITY AUDIT — [Dockerfile/Image name]\r\n   Date: [timestamp]\r\n\r\n   CRITICAL: [count]\r\n   HIGH:     [count]\r\n   MEDIUM:   [count]\r\n   LOW:      [count]\r\n\r\n   [Detailed findings with fix recommendations]\r\n   ```\r\n\r\n---\r\n\r\n## Tooling\r\n\r\n### `scripts/dockerfile_analyzer.py`\r\n\r\nCLI utility for static analysis of Dockerfiles.\r\n\r\n**Features:**\r\n- Layer count and optimization suggestions\r\n- Base image analysis with size estimates\r\n- Anti-pattern detection (15+ rules)\r\n- Security issue flagging\r\n- Multi-stage build detection and validation\r\n- JSON and text output\r\n\r\n**Usage:**\r\n```bash\r\n# Analyze a Dockerfile\r\npython3 scripts/dockerfile_analyzer.py Dockerfile\r\n\r\n# JSON output\r\npython3 scripts/dockerfile_analyzer.py Dockerfile --output json\r\n\r\n# Analyze with security focus\r\npython3 scripts/dockerfile_analyzer.py Dockerfile --security\r\n\r\n# Check a specific directory\r\npython3 scripts/dockerfile_analyzer.py path/to/Dockerfile\r\n```\r\n\r\n### `scripts/compose_validator.py`\r\n\r\nCLI utility for validating docker-compose files.\r\n\r\n**Features:**\r\n- Service dependency validation\r\n- Healthcheck presence detection\r\n- Network configuration analysis\r\n- Volume mount validation\r\n- Environment variable audit\r\n- Port conflict detection\r\n- Best practice scoring\r\n\r\n**Usage:**\r\n```bash\r\n# Validate a compose file\r\npython3 scripts/compose_validator.py docker-compose.yml\r\n\r\n# JSON output\r\npython3 scripts/compose_validator.py docker-compose.yml --output json\r\n\r\n# Strict mode (fail on warnings)\r\npython3 scripts/compose_validator.py docker-compose.yml --strict\r\n```\r\n\r\n---\r\n\r\n## Multi-Stage Build Patterns\r\n\r\n### Pattern 1: Compiled Language (Go, Rust, C++)\r\n\r\n```dockerfile\r\n# Build stage\r\nFROM golang:1.22-alpine AS builder\r\nWORKDIR /app\r\nCOPY go.mod go.sum ./\r\nRUN go mod download\r\nCOPY . .\r\nRUN CGO_ENABLED=0 go build -ldflags=\"-s -w\" -o /app/server ./cmd/server\r\n\r\n# Runtime stage\r\nFROM gcr.io/distroless/static-debian12\r\nCOPY --from=builder /app/server /server\r\nUSER nonroot:nonroot\r\nENTRYPOINT [\"/server\"]\r\n```\r\n\r\n### Pattern 2: Node.js / TypeScript\r\n\r\n```dockerfile\r\n# Dependencies stage\r\nFROM node:20-alpine AS deps\r\nWORKDIR /app\r\nCOPY package.json package-lock.json ./\r\nRUN npm ci --production=false\r\n\r\n# Build stage\r\nFROM deps AS builder\r\nCOPY . .\r\nRUN npm run build\r\n\r\n# Runtime stage\r\nFROM node:20-alpine\r\nWORKDIR /app\r\nRUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001\r\nCOPY --from=builder /app/dist ./dist\r\nCOPY --from=deps /app/node_modules ./node_modules\r\nCOPY package.json ./\r\nUSER appuser\r\nEXPOSE 3000\r\nCMD [\"node\", \"dist/index.js\"]\r\n```\r\n\r\n### Pattern 3: Python\r\n\r\n```dockerfile\r\n# Build stage\r\nFROM python:3.12-slim AS builder\r\nWORKDIR /app\r\nCOPY requirements.txt .\r\nRUN pip install --no-cache-dir --prefix=/install -r requirements.txt\r\n\r\n# Runtime stage\r\nFROM python:3.12-slim\r\nWORKDIR /app\r\nRUN groupadd -r appgroup && useradd -r -g appgroup appuser\r\nCOPY --from=builder /install /usr/local\r\nCOPY . .\r\nUSER appuser\r\nEXPOSE 8000\r\nCMD [\"python\", \"-m\", \"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\r\n```\r\n\r\n---\r\n\r\n## Base Image Decision Tree\r\n\r\n```\r\nIs it a compiled binary (Go, Rust, C)?\r\n├── Yes → distroless/static or scratch\r\n└── No\r\n    ├── Need a shell for debugging?\r\n    │   ├── Yes → alpine variant (e.g., node:20-alpine)\r\n    │   └── No → distroless variant\r\n    ├── Need glibc (not musl)?\r\n    │   ├── Yes → slim variant (e.g., python:3.12-slim)\r\n    │   └── No → alpine variant\r\n    └── Need specific OS packages?\r\n        ├── Many → debian-slim\r\n        └── Few → alpine + apk add\r\n```\r\n\r\n---\r\n\r\n## Proactive Triggers\r\n\r\nFlag these without being asked:\r\n\r\n- **Dockerfile uses :latest** → Suggest pinning to a specific version tag.\r\n- **No .dockerignore** → Create one. At minimum: `.git`, `node_modules`, `__pycache__`, `.env`.\r\n- **COPY . . before dependency install** → Cache bust. Reorder to install deps first.\r\n- **Running as root** → Add USER instruction. No exceptions for production.\r\n- **Secrets in ENV or ARG** → Use BuildKit secret mounts. Never bake secrets into layers.\r\n- **Image over 1GB** → Multi-stage build required. No reason for a production image this large.\r\n- **No healthcheck** → Add one. Orchestrators (Compose, K8s) need it for proper lifecycle management.\r\n- **apt-get without cleanup in same layer** → `rm -rf /var/lib/apt/lists/*` in the same RUN.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### One-liner (any tool)\r\n```bash\r\ngit clone https://github.com/alirezarezvani/claude-skills.git\r\ncp -r claude-skills/engineering/docker-development ~/.claude/skills/\r\n```\r\n\r\n### Multi-tool install\r\n```bash\r\n./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw\r\n```\r\n\r\n### OpenClaw\r\n```bash\r\nclawhub install cs-docker-development\r\n```\r\n\r\n---\r\n\r\n## Related Skills\r\n\r\n- **senior-devops** — Broader DevOps scope (CI/CD, IaC, monitoring). Complementary — use docker-development for container-specific work, senior-devops for pipeline and infrastructure.\r\n- **senior-security** — Application security. Complementary — docker-development covers container security, senior-security covers application-level threats.\r\n- **autoresearch-agent** — Can optimize Docker build times or image sizes as measurable experiments.\r\n- **ci-cd-pipeline-builder** — Pipeline construction. Complementary — docker-development builds the containers, ci-cd-pipeline-builder deploys them.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The docker-development/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/docker-development",
    "exported_at": "2026-11-03T07:41:04.373Z"
  }
}

format: aiskill/v1
skill:
  name: docker-development
  slug: docker-development
  version: 1.0.0
  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.
  category: Development
  tags:
    - engineering
    - devops
    - security
    - agents
    - performance
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Docker Development\r\n\r\n> Smaller images. Faster builds. Secure containers. No guesswork.\r\n\r\nOpinionated Docker workflow that turns bloated Dockerfiles into production-grade containers. Covers optimization, multi-stage builds, compose orchestration, and security hardening.\r\n\r\nNot a Docker tutorial — a set of concrete decisions about how to build containers that don't waste time, space, or attack surface.\r\n\r\n---\r\n\r\n## Slash Commands\r\n\r\n| Command | What it does |\r\n|---------|-------------|\r\n| `/docker:optimize` | Analyze and optimize a Dockerfile for size, speed, and layer caching |\r\n| `/docker:compose` | Generate or improve docker-compose.yml with best practices |\r\n| `/docker:security` | Audit a Dockerfile or running container for security issues |\r\n\r\n---\r\n\r\n## When This Skill Activates\r\n\r\nRecognize these patterns from the user:\r\n\r\n- \"Optimize this Dockerfile\"\r\n- \"My Docker build is slow\"\r\n- \"Create a docker-compose for this project\"\r\n- \"Is this Dockerfile secure?\"\r\n- \"Reduce my Docker image size\"\r\n- \"Set up multi-stage builds\"\r\n- \"Docker best practices for [language/framework]\"\r\n- Any request involving: Dockerfile, docker-compose, container, image size, build cache, Docker security\r\n\r\nIf the user has a Dockerfile or wants to containerize something → this skill applies.\r\n\r\n---\r\n\r\n## Workflow\r\n\r\n### `/docker:optimize` — Dockerfile Optimization\r\n\r\n1. **Analyze current state**\r\n   - Read the Dockerfile\r\n   - Identify base image and its size\r\n   - Count layers (each RUN/COPY/ADD = 1 layer)\r\n   - Check for common anti-patterns\r\n\r\n2. **Apply optimization checklist**\r\n\r\n   ```\r\n   BASE IMAGE\r\n   ├── Use specific tags, never :latest in production\r\n   ├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)\r\n   ├── Pin digest for reproducibility in CI: image@sha256:...\r\n   └── Match base to runtime needs (don't use python:3.12 for a compiled binary)\r\n\r\n   LAYER OPTIMIZATION\r\n   ├── Combine related RUN commands with && \\\r\n   ├── Order layers: least-changing first (deps before source code)\r\n   ├── Clean package manager cache in the same RUN layer\r\n   ├── Use .dockerignore to exclude unnecessary files\r\n   └── Separate build deps from runtime deps\r\n\r\n   BUILD CACHE\r\n   ├── COPY dependency files before source code (package.json, requirements.txt, go.mod)\r\n   ├── Install deps in a separate layer from code copy\r\n   ├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache\r\n   └── Avoid COPY . . before dependency installation\r\n\r\n   MULTI-STAGE BUILDS\r\n   ├── Stage 1: build (full SDK, build tools, dev deps)\r\n   ├── Stage 2: runtime (minimal base, only production artifacts)\r\n   ├── COPY --from=builder only what's needed\r\n   └── Final image should have NO build tools, NO source code, NO dev deps\r\n   ```\r\n\r\n3. **Generate optimized Dockerfile**\r\n   - Apply all relevant optimizations\r\n   - Add inline comments explaining each decision\r\n   - Report estimated size reduction\r\n\r\n4. **Validate**\r\n   ```bash\r\n   python3 scripts/dockerfile_analyzer.py Dockerfile\r\n   ```\r\n\r\n### `/docker:compose` — Docker Compose Configuration\r\n\r\n1. **Identify services**\r\n   - Application (web, API, worker)\r\n   - Database (postgres, mysql, redis, mongo)\r\n   - Cache (redis, memcached)\r\n   - Queue (rabbitmq, kafka)\r\n   - Reverse proxy (nginx, traefik, caddy)\r\n\r\n2. **Apply compose best practices**\r\n\r\n   ```\r\n   SERVICES\r\n   ├── Use depends_on with condition: service_healthy\r\n   ├── Add healthchecks for every service\r\n   ├── Set resource limits (mem_limit, cpus)\r\n   ├── Use named volumes for persistent data\r\n   └── Pin image versions\r\n\r\n   NETWORKING\r\n   ├── Create explicit networks (don't rely on default)\r\n   ├── Separate frontend and backend networks\r\n   ├── Only expose ports that need external access\r\n   └── Use internal: true for backend-only networks\r\n\r\n   ENVIRONMENT\r\n   ├── Use env_file for secrets, not inline environment\r\n   ├── Never commit .env files (add to .gitignore)\r\n   ├── Use variable substitution: ${VAR:-default}\r\n   └── Document all required env vars\r\n\r\n   DEVELOPMENT vs PRODUCTION\r\n   ├── Use compose profiles or override files\r\n   ├── Dev: bind mounts for hot reload, debug ports exposed\r\n   ├── Prod: named volumes, no debug ports, restart: unless-stopped\r\n   └── docker-compose.override.yml for dev-only config\r\n   ```\r\n\r\n3. **Generate compose file**\r\n   - Output docker-compose.yml with healthchecks, networks, volumes\r\n   - Generate .env.example with all required variables documented\r\n   - Add dev/prod profile annotations\r\n\r\n### `/docker:security` — Container Security Audit\r\n\r\n1. **Dockerfile audit**\r\n\r\n   | Check | Severity | Fix |\r\n   |-------|----------|-----|\r\n   | Running as root | Critical | Add `USER nonroot` after creating user |\r\n   | Using :latest tag | High | Pin to specific version |\r\n   | Secrets in ENV/ARG | Critical | Use BuildKit secrets: `--mount=type=secret` |\r\n   | COPY with broad glob | Medium | Use specific paths, add .dockerignore |\r\n   | Unnecessary EXPOSE | Low | Only expose ports the app uses |\r\n   | No HEALTHCHECK | Medium | Add HEALTHCHECK with appropriate interval |\r\n   | Privileged instructions | High | Avoid `--privileged`, drop capabilities |\r\n   | Package manager cache retained | Low | Clean in same RUN layer |\r\n\r\n2. **Runtime security checks**\r\n\r\n   | Check | Severity | Fix |\r\n   |-------|----------|-----|\r\n   | Container running as root | Critical | Set user in Dockerfile or compose |\r\n   | Writable root filesystem | Medium | Use `read_only: true` in compose |\r\n   | All capabilities retained | High | Drop all, add only needed: `cap_drop: [ALL]` |\r\n   | No resource limits | Medium | Set `mem_limit` and `cpus` |\r\n   | Host network mode | High | Use bridge or custom network |\r\n   | Sensitive mounts | Critical | Never mount /etc, /var/run/docker.sock in prod |\r\n   | No log driver configured | Low | Set `logging:` with size limits |\r\n\r\n3. **Generate security report**\r\n   ```\r\n   SECURITY AUDIT — [Dockerfile/Image name]\r\n   Date: [timestamp]\r\n\r\n   CRITICAL: [count]\r\n   HIGH:     [count]\r\n   MEDIUM:   [count]\r\n   LOW:      [count]\r\n\r\n   [Detailed findings with fix recommendations]\r\n   ```\r\n\r\n---\r\n\r\n## Tooling\r\n\r\n### `scripts/dockerfile_analyzer.py`\r\n\r\nCLI utility for static analysis of Dockerfiles.\r\n\r\n**Features:**\r\n- Layer count and optimization suggestions\r\n- Base image analysis with size estimates\r\n- Anti-pattern detection (15+ rules)\r\n- Security issue flagging\r\n- Multi-stage build detection and validation\r\n- JSON and text output\r\n\r\n**Usage:**\r\n```bash\r\n# Analyze a Dockerfile\r\npython3 scripts/dockerfile_analyzer.py Dockerfile\r\n\r\n# JSON output\r\npython3 scripts/dockerfile_analyzer.py Dockerfile --output json\r\n\r\n# Analyze with security focus\r\npython3 scripts/dockerfile_analyzer.py Dockerfile --security\r\n\r\n# Check a specific directory\r\npython3 scripts/dockerfile_analyzer.py path/to/Dockerfile\r\n```\r\n\r\n### `scripts/compose_validator.py`\r\n\r\nCLI utility for validating docker-compose files.\r\n\r\n**Features:**\r\n- Service dependency validation\r\n- Healthcheck presence detection\r\n- Network configuration analysis\r\n- Volume mount validation\r\n- Environment variable audit\r\n- Port conflict detection\r\n- Best practice scoring\r\n\r\n**Usage:**\r\n```bash\r\n# Validate a compose file\r\npython3 scripts/compose_validator.py docker-compose.yml\r\n\r\n# JSON output\r\npython3 scripts/compose_validator.py docker-compose.yml --output json\r\n\r\n# Strict mode (fail on warnings)\r\npython3 scripts/compose_validator.py docker-compose.yml --strict\r\n```\r\n\r\n---\r\n\r\n## Multi-Stage Build Patterns\r\n\r\n### Pattern 1: Compiled Language (Go, Rust, C++)\r\n\r\n```dockerfile\r\n# Build stage\r\nFROM golang:1.22-alpine AS builder\r\nWORKDIR /app\r\nCOPY go.mod go.sum ./\r\nRUN go mod download\r\nCOPY . .\r\nRUN CGO_ENABLED=0 go build -ldflags=\"-s -w\" -o /app/server ./cmd/server\r\n\r\n# Runtime stage\r\nFROM gcr.io/distroless/static-debian12\r\nCOPY --from=builder /app/server /server\r\nUSER nonroot:nonroot\r\nENTRYPOINT [\"/server\"]\r\n```\r\n\r\n### Pattern 2: Node.js / TypeScript\r\n\r\n```dockerfile\r\n# Dependencies stage\r\nFROM node:20-alpine AS deps\r\nWORKDIR /app\r\nCOPY package.json package-lock.json ./\r\nRUN npm ci --production=false\r\n\r\n# Build stage\r\nFROM deps AS builder\r\nCOPY . .\r\nRUN npm run build\r\n\r\n# Runtime stage\r\nFROM node:20-alpine\r\nWORKDIR /app\r\nRUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001\r\nCOPY --from=builder /app/dist ./dist\r\nCOPY --from=deps /app/node_modules ./node_modules\r\nCOPY package.json ./\r\nUSER appuser\r\nEXPOSE 3000\r\nCMD [\"node\", \"dist/index.js\"]\r\n```\r\n\r\n### Pattern 3: Python\r\n\r\n```dockerfile\r\n# Build stage\r\nFROM python:3.12-slim AS builder\r\nWORKDIR /app\r\nCOPY requirements.txt .\r\nRUN pip install --no-cache-dir --prefix=/install -r requirements.txt\r\n\r\n# Runtime stage\r\nFROM python:3.12-slim\r\nWORKDIR /app\r\nRUN groupadd -r appgroup && useradd -r -g appgroup appuser\r\nCOPY --from=builder /install /usr/local\r\nCOPY . .\r\nUSER appuser\r\nEXPOSE 8000\r\nCMD [\"python\", \"-m\", \"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\r\n```\r\n\r\n---\r\n\r\n## Base Image Decision Tree\r\n\r\n```\r\nIs it a compiled binary (Go, Rust, C)?\r\n├── Yes → distroless/static or scratch\r\n└── No\r\n    ├── Need a shell for debugging?\r\n    │   ├── Yes → alpine variant (e.g., node:20-alpine)\r\n    │   └── No → distroless variant\r\n    ├── Need glibc (not musl)?\r\n    │   ├── Yes → slim variant (e.g., python:3.12-slim)\r\n    │   └── No → alpine variant\r\n    └── Need specific OS packages?\r\n        ├── Many → debian-slim\r\n        └── Few → alpine + apk add\r\n```\r\n\r\n---\r\n\r\n## Proactive Triggers\r\n\r\nFlag these without being asked:\r\n\r\n- **Dockerfile uses :latest** → Suggest pinning to a specific version tag.\r\n- **No .dockerignore** → Create one. At minimum: `.git`, `node_modules`, `__pycache__`, `.env`.\r\n- **COPY . . before dependency install** → Cache bust. Reorder to install deps first.\r\n- **Running as root** → Add USER instruction. No exceptions for production.\r\n- **Secrets in ENV or ARG** → Use BuildKit secret mounts. Never bake secrets into layers.\r\n- **Image over 1GB** → Multi-stage build required. No reason for a production image this large.\r\n- **No healthcheck** → Add one. Orchestrators (Compose, K8s) need it for proper lifecycle management.\r\n- **apt-get without cleanup in same layer** → `rm -rf /var/lib/apt/lists/*` in the same RUN.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### One-liner (any tool)\r\n```bash\r\ngit clone https://github.com/alirezarezvani/claude-skills.git\r\ncp -r claude-skills/engineering/docker-development ~/.claude/skills/\r\n```\r\n\r\n### Multi-tool install\r\n```bash\r\n./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw\r\n```\r\n\r\n### OpenClaw\r\n```bash\r\nclawhub install cs-docker-development\r\n```\r\n\r\n---\r\n\r\n## Related Skills\r\n\r\n- **senior-devops** — Broader DevOps scope (CI/CD, IaC, monitoring). Complementary — use docker-development for container-specific work, senior-devops for pipeline and infrastructure.\r\n- **senior-security** — Application security. Complementary — docker-development covers container security, senior-security covers application-level threats.\r\n- **autoresearch-agent** — Can optimize Docker build times or image sizes as measurable experiments.\r\n- **ci-cd-pipeline-builder** — Pipeline construction. Complementary — docker-development builds the containers, ci-cd-pipeline-builder deploys them."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The docker-development/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/docker-development
  exported_at: "2026-11-03T07:41:04.373Z"