Zero-Host-Dependency Orchestration with Docker & Makefile Agent Skill

The Chaos of Ambient Host Dependencies

How many times have you onboarded a new developer—or prompted an autonomous AI coding assistant (Claude Code, Gemini/Antigravity, Cursor, Codex)—only to encounter these classic roadblocks?

• "You need Node v22.1.0, but your machine has v18.14.0."

• "The test suite failed because Chromium or Xdebug isn't installed on the host."

• "The AI agent started executing random, ad-hoc npm/pip/composer scripts and created files with root permissions."

• "The production Dockerfile is running as root and shipping a full Debian OS with compilers and shell access."

The root cause is relying on ambient host dependencies. When your project assumes that runtimes, packages, linters, and databases are scattered across individual developer laptops, reproducibility disappears and AI agents struggle to execute commands reliably.

To eliminate this friction once and for all, I open-sourced docker-and-orchestration, a canonical agent skill adhering to the Agent Skills Open Specification (agentskills.io) and distributed via skills.sh.

🛡️ The Core Invariant: Zero Host Dependencies

The philosophy behind this skill is uncompromising:

The host machine requires ONLY Docker (with Compose) and GNU Make.
100% of runtimes (Bun, Node, PHP, Go, Python), package managers, linters, test runners, and database CLIs MUST execute inside isolated, reproducible containers.

🏛️ The 3 Architectural Pillars

1. Makefile as the Universal Orchestration Layer

Instead of having human engineers or AI agents remember complex, brittle shell commands, the Makefile acts as the single source of truth for all workflows:

make help             # Self-documenting, formatted command menu
make install          # Containerized dependency installation
make dev              # Hot-reloading development environment (docker-compose)
make test             # Ephemeral unit & integration test runners
make check            # Pre-commit pipeline (typecheck + lint + audit + test)
make build            # Multi-stage production container build

⚡ The Ephemeral Runner Pattern

For static analysis, typechecking, and unit tests, the skill enforces ephemeral runners that spin up, execute, and destroy containers immediately with zero lingering resources:

DOCKER_RUN := $(COMPOSE_DEV) run --rm --no-deps

test: ## Runs unit tests inside ephemeral container
	$(DOCKER_RUN) api bun run test

lint: ## Runs linters inside ephemeral container
	$(DOCKER_RUN) api bun run lint

2. Multi-Stage Hardened Containers (Base ➔ Test ➔ Distroless)

The skill guides agents to craft secure, 3-stage Dockerfiles:

1. Stage 1 (Base & Deps Builder): Caches manifests (package.json, bun.lock, go.mod), enforces frozen lockfiles, and passes --ignore-scripts to block malicious supply-chain lifecycle hooks.

2. Stage 2 (Test & Dev Runner): Equipped with test toolchains (e.g. Playwright, headless Chromium, Xdebug) and runs as a dedicated non-root user.

3. Stage 3 (Production Distroless / Scratch): Copies only the compiled application binary or runtime bundle into a Distroless/Scratch image. Zero OS package managers, zero shell (/bin/sh), and strict non-root execution (USER 1000:1000).

3. Split Docker Compose Topology

Never pollute production definitions with local development conveniences. The skill enforces a clean two-tier compose strategy:

• docker-compose.yml (Base): Clean, production-aligned service declarations, networking, and environment configurations.

• docker-compose.dev.yml (Overrides): Local hot-reload volume mounts (./:/app) and debugging ports (e.g., V8 inspector or Xdebug 9003).

The Makefile merges both files deterministically:

COMPOSE     := docker compose -f docker-compose.yml
COMPOSE_DEV := docker compose -f docker-compose.yml -f docker-compose.dev.yml

🔒 Built-in Security & Vulnerability Auditing

Security is treated as a first-class citizen with Docker Scout and supply-chain auditing built directly into the workflow:

• Non-root enforcement: Containers never run as UID 0 in runtime.

• Supply-chain locking: --ignore-scripts and frozen lockfiles are mandatory.

• Automated CVE Scanning: A dedicated make audit-image target scans production images for Critical and High vulnerabilities before deployment:

  docker scout cves --only-severity critical,high <image-name>:latest
  

🚀 How It Works with QRSPI in Practice

When paired with the qrspi-methodology skill, AI coding assistants become unstoppable:

1. You give a natural prompt: "Build a key-value caching service with TTL from scratch."

2. QRSPI triggers to structure the 5-phase engineering protocol (interrogating requirements, mapping blast radius, establishing living ADRs, and pausing at each turn).

3. Docker & Orchestration triggers to scaffold the entire infrastructure with zero host dependencies: a hardened multi-stage Dockerfile, split compose configuration, and an ergonomic Makefile.

📦 Universal Installation via skills.sh

Install the skill into your project or globally on your system in seconds:

# Add to current workspace
npx skills add racastellanosm/agent-skills --skill docker-and-orchestration

# Or install all engineering skills in the catalog
npx skills add racastellanosm/agent-skills

# Install globally for all projects on your machine
npx skills add racastellanosm/agent-skills -g

🤖 Multi-Harness Interoperability

Works out of the box with Claude Code, Google Gemini & Antigravity, OpenAI Codex, Cursor, Cline, and OpenCode.

💡 Explore the Code & Contribute

Both skills are 100% open-source under the MIT license:

• 🌟 GitHub Repository: github.com/racastellanosm/agent-skills

• 📖 Skill Documentation: skills/docker-and-orchestration

• 📦 Registry: skills.sh/racastellanosm/agent-skills

How do you manage container orchestration and developer tooling in your team? Let me know in the comments below!