name: docker
description: |
Production-grade Docker containerization for Python and Node.js applications.
This skill should be used when users ask to containerize applications, create Dockerfiles,
dockerize projects, or set up Docker Compose. Auto-detects project structure,
analyzes .env for secrets, validates security, and generates tested Dockerfiles.
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-docker.sh"

Docker

Production-grade Docker containerization with security-first defaults.

Resource Detection & Adaptation

Before generating Dockerfiles/Compose, detect the environment:

# Detect host machine memory
sysctl -n hw.memsize 2>/dev/null | awk '{print $0/1024/1024/1024 " GB"}' || \
  grep MemTotal /proc/meminfo | awk '{print $2/1024/1024 " GB"}'

# Detect Docker allocated resources
docker info --format 'Memory: {{.MemTotal}}, CPUs: {{.NCPU}}'

# Detect available disk space
docker system df

Adapt configurations based on detection:

Agent Behavior

1. Detect Docker resources before generating compose.yaml
2. Adapt resource limits to available memory
3. Warn if build may fail due to insufficient resources
4. Calculate safe limits: docker_memory * 0.6 / container_count

Adaptive Compose Templates

Constrained (< 4GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.25'
    build:
      args:
        - BUILDKIT_STEP_LOG_MAX_SIZE=10000000

⚠️ Agent should warn: "Docker memory low. Multi-stage builds may fail."

Standard (4-8GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M

Extended (> 8GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M

Pre-Build Validation

Before running docker build, agent should verify:

# Check available memory
docker info --format '{{.MemTotal}}' | awk '{if ($1 < 4000000000) print "WARNING: Low memory"}'

If constrained: use --memory flag and warn user about potential build failures.

What This Skill Does

Analysis & Detection:
- Auto-detects runtime, framework, version, entrypoint (no questions)
- Scans .env files, classifies secrets vs build-args vs runtime config
- Detects native dependencies, generates correct build deps
- Identifies missing configs (Next.js standalone, health endpoints)

Generation:
- Creates multi-stage Dockerfiles customized to YOUR project structure
- Generates compose.yaml with security defaults (non-root, read-only, resource limits)
- Adds health endpoints if missing
- Fixes configuration issues (adds output: 'standalone' to Next.js, etc.)

Validation:
- Builds both dev and production targets before delivering
- Verifies health endpoints work
- Confirms non-root user in production
- Warns about any secrets that would leak into image
- Reports image size

Security:
- Never bakes secrets into images
- Non-root user by default
- Minimal attack surface (multi-stage builds)
- Pinned versions (no :latest)
- Security scan command included

What This Skill Does NOT Do

• Generate Kubernetes manifests (use dedicated k8s skill)
• Create Helm charts (use dedicated helm skill)
• Handle Bun/Deno (use dedicated skills)
• Copy templates blindly without customization

Before Implementation

Gather context to ensure successful implementation:

Required Clarifications

Ask when not auto-detectable:

Detect Runtime

Auto-Detection (Do NOT ask - detect from files)

Python

Node.js

Fix Issues Automatically

Workflow

1. SCAN PROJECT
   - Detect runtime, framework, version, entrypoint
   - Find dependency files, native deps
   - Locate existing Docker files (don't blindly overwrite)
         ↓
2. ANALYZE ENVIRONMENT
   - Scan all .env* files
   - Classify: SECRET (never bake) / BUILD_ARG / RUNTIME
   - Flag security issues
         ↓
3. FIX CONFIGURATION
   - Add Next.js `output: 'standalone'` if missing
   - Create health endpoints if missing
   - Generate .env.example with safe placeholders
         ↓
4. GENERATE FILES
   - Dockerfile (customized CMD, paths, build deps)
   - .dockerignore (excludes .env, secrets)
   - compose.yaml (with security defaults)
         ↓
5. VALIDATE & TEST
   - docker build --target dev -t app:dev .
   - docker build --target production -t app:prod .
   - Test health endpoints
   - Verify non-root user
   - Report image size
         ↓
6. DELIVER WITH CONTEXT
   - All files with explanations
   - Security scan command
   - Any warnings about secrets
   - Rollback instructions if replacing existing

Only ask if genuinely ambiguous (e.g., multiple apps in monorepo, conflicting configs)

Base Image Decision Matrix

Default: Slim (works everywhere without authentication)

Stage Structure

deps/base  → Install dependencies (cached layer)
    ↓
builder    → Build/compile application
    ↓
dev        → Hot-reload, volume mounts (--target dev)
    ↓
production → Minimal DHI runtime (--target production)

Build Commands

docker build --target dev -t myapp:dev .
docker build --target production -t myapp:prod .

Python Patterns

Framework CMD

Cache Mount (uv/pip)

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=cache,target=/root/.cache/pip \
    uv pip install -r requirements.txt

Graceful Shutdown (FastAPI)

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield  # startup
    # shutdown logic here

Node.js Patterns

Framework Build

Cache Mounts

# pnpm
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile

# npm
RUN --mount=type=cache,target=/root/.npm npm ci

# yarn
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn \
    yarn install --frozen-lockfile

Graceful Shutdown (Node.js)

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

Security Checklist

Before delivering, verify:

• [ ] Non-root USER in production stage
• [ ] No secrets in Dockerfile or image layers
• [ ] .dockerignore excludes .env, .git, secrets
• [ ] Multi-stage separates build tools from runtime
• [ ] DHI or hardened base image used
• [ ] HEALTHCHECK instruction defined
• [ ] No package install in production stage
• [ ] Secrets via runtime env vars or mounted files

Output Files

Reference Files

Always Read First

Framework-Specific

Optional

Templates (Reference Patterns)

Templates in templates/ are reference patterns, not copy-paste files.

Agent must:
1. Read template to understand structure
2. Customize paths, CMDs, and stages for actual project
3. Generate Dockerfile with correct entrypoint (e.g., src.app.main:app)
4. Never output placeholder comments like "# Replace based on framework"

Example customization:

# Template says:
CMD ["uvicorn", "app.main:app", ...]

# Agent detects app at src/api/main.py, generates:
CMD ["uvicorn", "src.api.main:app", ...]