The Complete Production SOP: How to Deploy and Run Dive Docker Image Layer Inspection & Efficiency Profiler in Autonomous AI Agents
Step-by-step SOP to install and run Dive Docker Image Layer Explorer in Codex, Claude Code, and Cursor. Audit wasted space and enforce CI image efficiency.
Technical Overview & Architectural Context
Container image optimization is notorious for subtle anti-patterns that autonomous coding agents fail to detect when relying solely on static Dockerfile text analysis. Agents frequently introduce inefficient multi-stage build artifacts, accidentally bust Docker layer caching, leave temporary package manager caches (like /var/cache/apt or ~/.cache/pip) trapped inside intermediate read-only image layers, or overwrite large binaries across successive RUN commands without realizing image disk sizes accumulate monotonically in OCI storage. Without the Dive Docker Image Layer Inspection & Efficiency Profiler skill, agents execute unvalidated docker build commands, naively believing an image is optimized because its total size appears moderate. They lack deterministic runtime feedback on layer-by-layer file mutations, wasted duplicate bytes, and file system diffs between layers. This results in bloated production container registries, slow deployment pipelines, and silent layer-cache bloat. This skill binds Codex, Claude Code, Cursor, and Windsurf to a strict container evaluation harness. By injecting Dive's non-interactive CI inspection capabilities (--ci-config) alongside strict efficiency criteria, agents are constrained to programmatically inspect image layers, measure image efficiency scores (0-100%), isolate overwritten duplicate files, and assert strict gate thresholds (e.g., minimum 95% efficiency, maximum 50MB wasted bytes) prior to merging code.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules.
To enable your coding agent (Codex, Claude Code, Cursor, or Windsurf) to discover and execute the Dive inspection SOP, mount the standardized SKILL.md file into your repository's local agent configuration path (.agents/skills/ or .claude/skills/). Autonomous agents automatically read the YAML frontmatter triggers and lock into procedural rules when container layer queries occur.
mkdir -p .agents/skills/dive-docker-image-layer-explorer && curl -fsSL https://askills.dev/api/skills/dive-docker-image-layer-explorer/raw -o .agents/skills/dive-docker-image-layer-explorer/SKILL.md---
name: "dive-docker-image-layer-explorer"
description: "Explore Docker image layers, discover wasted duplicate space, and verify CI image efficiency."
metadata:
author: "Alex Goodman"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "inspect docker layers dive"
- "find wasted space docker image"
- "enforce dive image efficiency ci"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Dive Docker Image Layer Inspection & Efficiency Profiler
Analyzes container images with Dive: inspecting layer by layer file diffs, measuring image efficiency score (0-100%), detecting duplicate overwritten files, and automating CI efficiency thresholds.
## Execution SOP & Rules
1. Build target image: docker build -t local-eval/target:latest .
2. Execute programmatic analysis: CI=true dive local-eval/target:latest --ci-config .dive-ci.yaml
3. Parse reported wasted bytes and efficiency metric.
4. Refactor Dockerfile to collapse multi-layer writes and purge package caches within the same RUN layer.
5. Re-run verification until efficiency >= 0.95 and wasted bytes <= 50MB.Keep the SKILL.md focused solely on declarative SOP constraints. Instructing agents to use Dive's CI mode prevents them from spawning interactive TUI processes that deadlock automated agent subprocess shells.
Never allow agents to invoke raw `dive <image>` without the `CI=true` flag inside autonomous execution loops; interactive terminal emulation blocks standard non-TTY agent runners.
Environment Secrets & Dependency Validation
Inject required environment variables safely without leaking secrets into conversation history.
Ensure the Dive binary and Docker daemon connection are validated inside the agent's execution shell. Establish the project-level .dive-ci.yaml specification containing strict efficiency thresholds, while safeguarding any registry credentials by binding them through environment configurations rather than inline chat tokens.
which dive || (echo "Dive CLI not found in PATH"; exit 1) && docker info >/dev/null 2>&1 || (echo "Docker daemon inaccessible"; exit 1)rules:
# Image efficiency must exceed 95% (0.95)
lowestEfficiency: 0.95
# Total wasted space across all layers must not exceed 25MB
highestWastedBytes: 26214400
# Disallow individual duplicate files exceeding 5MB
highestUserWastedPercent: 0.05Store project-level thresholds in .dive-ci.yaml in your root repository. The agent can reference this static file without repeatedly re-generating threshold parameters in its reasoning tokens.
If running inside rootless Docker or containerized agent sandboxes (e.g., devcontainers), ensure /var/run/docker.sock is explicitly mounted with write permissions for the agent's UID.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts.
Invoke the agent using precise intent phrasing mapped to the frontmatter triggers (`inspect docker layers dive`, `find wasted space docker image`, or `enforce dive image efficiency ci`). The agent selects the SOP, builds the local container context, and launches Dive in headless evaluation mode.
#!/usr/bin/env bash
set -euo pipefail
IMAGE_TAG="staging/app:audit-$(git rev-parse --short HEAD)"
echo "Building image: ${IMAGE_TAG}..."
docker build -t "${IMAGE_TAG}" .
echo "Running Dive layer audit in CI mode..."
CI=true dive "${IMAGE_TAG}" --ci-config .dive-ci.yaml --source dockerUse concise verbs matching the frontmatter triggers. Instruct the agent to capture the standard output to isolate duplicate file paths flagged by Dive.
Specifying `--source docker` prevents Dive from attempting to pull non-existent remote tags from Docker Hub when inspecting local development builds.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks before accepting agent deliverables.
Enforce a closed-loop quality gate: if Dive reports an efficiency score below the configured limit, the agent must parse the offending layer IDs, identify which intermediate files were created and later removed or overwritten, refactor the Dockerfile, and re-execute the evaluation until the exit code is 0.
CI=true dive staging/app:audit-$(git rev-parse --short HEAD) --ci-config .dive-ci.yaml && hadolint Dockerfile# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
corepack enable pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
# Avoid keeping temporary cache artifacts in final image layer
RUN addgroup --system --gid 1001 nodejs && \
adduser --system --uid 1001 nextjs
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]Always pair Dive efficiency audits with Hadolint to catch both static Dockerfile anti-patterns and runtime OCI layer payload regressions simultaneously.
Agents often attempt to reduce image size by running `rm -rf /tmp/*` in a subsequent `RUN` statement. Remind the agent that deleting files in a new layer does not recover space allocated in prior layers.
Real-World Scenario: Eliminating Redundant APT Caches and Node Modules in Production API Image
“Inspect docker layers dive for our production backend Dockerfile. Our latest build is over 1.4GB. Find wasted space docker image layers and enforce dive image efficiency ci so efficiency is >= 95% and wasted bytes are under 25MB.”
Runtime Troubleshooting & Failure Modes
Root Cause: The Dockerfile performed file system operations across multiple layers where files created in an early layer were overwritten or deleted in a later RUN command, retaining the original bytes in immutable base layers.
# Consolidate file creation, modification, and purge commands into a single RUN layer
RUN apt-get update && apt-get install -y --no-install-recommends curl jq \
&& rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*Root Cause: The agent runtime sandbox lacks permission to interact with the host Docker socket, or the Docker socket is mounted with root-only permissions under a non-root agent execution user.
sudo chmod 666 /var/run/docker.sock || sudo usermod -aG docker $USERFrequently Asked Questions (Dive Docker Image Layer Inspection & Efficiency Profiler SOP)
Q:Can I use Dive Docker Image Layer Inspection & Efficiency Profiler across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill adheres strictly to the open SKILL.md specification. When placed in `.agents/skills/dive-docker-image-layer-explorer` or referenced in workspace settings, Codex, Claude Code, Cursor, and Windsurf parse the frontmatter triggers and SOP rules uniformly.
Q:How does Dive Docker Image Layer Inspection & Efficiency Profiler prevent context window overflow during long agent sessions?
By forcing Dive to execute in non-interactive CI mode (`CI=true dive <image> --ci-config .dive-ci.yaml`), the tool emits concise summary metrics (efficiency percentage, wasted bytes list) rather than spewing extensive terminal escape codes or full layer file trees, preserving over 80% of the agent's context token window.
Q:Does this skill require escalated root or container permissions?
The skill has a security audit score of 98/100 and does not execute network requests or modify root host files. It requires read-only access to `/var/run/docker.sock` to inspect container image manifests locally, with file mutations restricted strictly to the project workspace.
Ready to equip your autonomous agent with Dive Docker Image Layer Inspection & Efficiency Profiler?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.