docker-development

Imported from borghei/claude-skills (engineering/docker-development/SKILL.md). Install upstream with npx skills add borghei/claude-skills --skill docker-development. Copyright stays with the author (MIT + Commons Clause).

Docker Development

Category: Engineering Domain: Container Development & Optimization

Overview

The Docker Development skill provides automated analysis of Dockerfiles and docker-compose configurations. It identifies layer optimization opportunities, security issues, best practice violations, and compose service misconfigurations. Use this skill to enforce container standards across your team and catch issues before they reach production.

Clarify First

Before running the analysis, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• Target file: which Dockerfile or docker-compose.yml to analyze (sets --file and which tool runs).
• Focus: full analysis vs security-only, and whether to check port conflicts (sets --security-only/--check-ports).
• Output mode: human-readable vs JSON for CI (sets --format json and whether findings gate a pipeline).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Quick Start

# Analyze a Dockerfile for best practices
python scripts/dockerfile_analyzer.py --file Dockerfile

# Analyze with JSON output
python scripts/dockerfile_analyzer.py --file Dockerfile --format json

# Validate a docker-compose file
python scripts/compose_validator.py --file docker-compose.yml

# Check for host port conflicts between services in one compose file
python scripts/compose_validator.py --file docker-compose.yml --check-ports

Tools Overview

dockerfile_analyzer.py

Analyzes Dockerfiles for best practices, security issues, and optimization opportunities.

# Full analysis
python scripts/dockerfile_analyzer.py --file Dockerfile

# Security-focused scan
python scripts/dockerfile_analyzer.py --file Dockerfile --security-only

# JSON output for CI integration
python scripts/dockerfile_analyzer.py --file Dockerfile --format json

compose_validator.py

Validates docker-compose files for correctness, dependency issues, and port conflicts.

# Full validation
python scripts/compose_validator.py --file docker-compose.yml

# Check port conflicts only
python scripts/compose_validator.py --file docker-compose.yml --check-ports

# JSON output
python scripts/compose_validator.py --file docker-compose.yml --format json

Workflows

Dockerfile Review Workflow

1. Analyze - Run dockerfile_analyzer.py against the target Dockerfile
2. Review findings - Address critical security issues first (root user, secrets)
3. Optimize layers - Combine RUN statements, reorder for cache efficiency
4. Validate base images - Switch to minimal base images where possible
5. Re-analyze - Confirm improvements and verify no regressions

Compose Validation Workflow

1. Validate structure - Run compose_validator.py for syntax and schema checks
2. Check dependencies - Review service dependency graph for circular refs
3. Audit ports - Ensure no host port conflicts across services
4. Review volumes - Confirm volume mounts are correct and necessary
5. Network review - Act on any host network mode warning, then check network definitions and service isolation by hand

CI Integration Workflow

# Example GitHub Actions step
- name: Docker Lint
  run: |
    python scripts/dockerfile_analyzer.py --file Dockerfile --format json > results.json
    python scripts/compose_validator.py --file docker-compose.yml --format json >> results.json

Scope & Limitations

In Scope:

• Dockerfile analysis with dockerfile_analyzer.py: layer count, multi-stage use, running as root, latest tags, secrets in the file, base image choice and cache-breaking instruction order, with --security-only for a narrower report
• Compose file checks with compose_validator.py: file structure, circular depends_on chains, duplicate host port bindings, volume mounts, security settings and best practices such as restart policies and resource limits
• Text or JSON output for review and CI steps
• Dockerfile and Compose patterns from the Docker best practices reference

Out of Scope:

• Building images, running containers or measuring real image size
• Scanning image layers or packages for known CVEs (dependency-level scanning is in engineering/dependency-auditor/)
• Kubernetes manifests and Helm charts (see engineering/kubernetes-operator/ and engineering/helm-chart-builder/)
• CI pipeline design around image builds (see engineering/devops-workflow-engineer/)

Important Caveats:

• Both tools read files as text. The Compose validator uses a small built-in YAML parser, so anchors, merge keys, extends, include and variable substitution may not be read correctly.
• compose_validator.py checks one file per run. Port conflicts or overrides spread across several Compose files are not detected.
• Base image advice is general. Whether alpine, slim or distroless suits an image depends on its libraries and needs a test build.
• A clean report means the rules found nothing. It is not a container security assessment.

Reference Documentation

• Docker Best Practices - Comprehensive guide to Dockerfile and Compose patterns

Common Patterns Quick Reference

Compose Patterns