Skip to content

sb-dev/openquant / .agents/skills/docker-build-strategies

docker-build-strategies

Flagged

Use this skill when writing, reviewing, or optimizing Dockerfiles, even if the user just says their image is too large, their build is slow, or they need to harden a container for production. Covers multi-stage builds, layer caching, .dockerignore, non-root users, and image size optimization.

checks/verification.md

View on GitHub
# Verification Runbook

Use these checks to verify a generated Dockerfile meets quality standards.

## Scripted verification

Run the bundled script from the project root (the directory that contains the `Dockerfile`), with the script path resolved under the skill directory:

```bash
bash "<skill-dir>/scripts/verify-build.sh" [--help] [IMAGE_NAME]
```

Replace `<skill-dir>` with the absolute path of this skill's directory, the folder that contains `SKILL.md` and this `checks/` folder. Do not change into the skill directory to run it; the script builds the current directory.

The image name defaults to `verify-build-test`. Exit status is `0` when the build and inspection commands succeed or help is requested, the failing Docker command's non-zero status when verification fails, and `2` for invalid arguments.

## 1. Build succeeds

```bash
docker buildx build -t test-image .
```

The build must complete without errors. Use `--progress=plain` to inspect each step if debugging is needed (avoid this flag in CI where build logs are persisted, since it may expose the content of any secret that a `RUN` step accidentally echoes).

## 2. Image size is reasonable

```bash
docker images test-image --format "{{.Size}}"
```

Expected baselines for a minimal application:

| Language | Reasonable upper bound |
|---|---|
| Go (distroless/scratch) | < 30 MB |
| Node.js (Alpine) | < 200 MB |
| Python (slim) | < 250 MB |
| Java (JRE Alpine) | < 300 MB |

If the image exceeds these bounds, check for:

- Missing multi-stage build (build tools included in runtime image)
- Large unnecessary files copied into the image
- Missing `.dockerignore`
- OS package caches baked into a layer instead of a BuildKit cache mount (`apt-get`/`apk`)

Use `docker history test-image` to identify which layers are largest.

## 3. Runs as non-root

```bash
docker run --rm test-image whoami
```

Expected output: `appuser`, `nonroot`, or another non-root username. Must not return `root`.

If the image does not have `whoami` (e.g., distroless), verify with:

```bash
docker inspect test-image --format '{{.Config.User}}'
```

The output must be non-empty and must not be `0` or `root`.

## 4. No secrets in image

### 4a. Static check of the Dockerfile pattern (primary)

Before building, verify the Dockerfile does not `COPY` credential files or pass credentials through `ARG`/`ENV`. Any match below is a leak:

```bash
# Credential files copied into the build context
grep -nE "^(COPY|ADD) .*(\.npmrc|\.pypirc|\.netrc|pip\.conf|settings\.xml|\.env|\.aws/credentials|\.config/gcloud|\.azure/|\.vault-token|\.cargo/credentials|id_(rsa|dsa|ed25519|ecdsa)|service.account.*\.json|\.pem([[:space:]]|$)|\.p12([[:space:]]|$)|kubeconfig)" Dockerfile

# Credentials passed as build args (visible in docker history) — case-insensitive
grep -inE "^ARG .*(TOKEN|KEY|SECRET|PASSWORD)" Dockerfile

# Credentials baked into image env (visible to anyone with the image) — case-insensitive
grep -inE "^ENV .*(TOKEN|KEY|SECRET|PASSWORD)=" Dockerfile
```

If the project needs registry credentials, the Dockerfile must use `RUN --mount=type=secret` and the build invocation must pass the secret:

```bash
docker buildx build --secret id=<id>,src=<host-path> --progress=plain .
```

The `--progress=plain` output should show the secret being consumed inside the right `RUN` step **without printing its value**. If you see the secret content in the log, the `RUN` is leaking it (e.g., via `echo`, `cat`, or shell substitution into a logged command) — that is a build-log leak even when the layer itself is clean. For private Git access, use `--mount=type=ssh` and `docker buildx build --ssh default .`, then run the SSH checks in 4c.

### 4b. Backstop: scan the built image

```bash
docker history test-image --no-trunc
```

Inspect the output for any `ENV` instructions or `COPY` steps that might include `.env` files, API keys, or credentials.

**Note:** `docker history` shows layers of the final exported image only. It will **not** reveal credentials that were `COPY`-ed in an intermediate stage but not carried forward — those files still exist in BuildKit's build cache on the builder host. The static Dockerfile check in 4a is the only way to catch that class of leak. This step is a backstop.

### 4c. SSH forwarding for private Git access

If the Dockerfile uses `RUN --mount=type=ssh`, check what the build can reach before running it:

```bash
# Every key listed here can be used by the RUN --mount=type=ssh step
ssh-add -l

# Host-key checking stays enabled (must return nothing)
grep -nE 'StrictHostKeyChecking[[:space:]=]+no' Dockerfile
```

- `ssh-add -l` should list only the key this build needs. If it lists more, run the build from a dedicated agent (in an interactive terminal, `ssh-agent bash`, then `ssh-add <key-file>`) instead of removing keys from the user's agent.
- The `RUN` that fetches over SSH populates `/root/.ssh/known_hosts` in the same step (for example with `ssh-keyscan`) instead of disabling host-key checking.
- `--ssh default=<key-file>` works only with an unencrypted key file. BuildKit rejects passphrase-protected keys in this form (`this private key is passphrase protected`), so load those into an agent and pass `--ssh default`.

## 5. Layer count

```bash
docker history test-image --format "{{.CreatedBy}}" | wc -l
```

A well-structured image typically has 8-15 layers. Significantly more may indicate missing command consolidation.

## 6. Correct WORKDIR, EXPOSE, and ENTRYPOINT

```bash
docker inspect test-image --format '{{.Config.WorkingDir}}'
docker inspect test-image --format '{{.Config.ExposedPorts}}'
docker inspect test-image --format '{{.Config.Entrypoint}}'
```

Verify:

- `WorkingDir` is set (not empty or `/`)
- `ExposedPorts` documents the expected port
- `Entrypoint` uses exec form (JSON array), not shell form

## 7. .dockerignore exists

Verify a `.dockerignore` file is present alongside the Dockerfile and excludes at minimum:

- `.git/`
- `node_modules/`, `__pycache__/`, or equivalent language artifacts
- `.env` and secret files
- IDE configuration directories

## 8. BuildKit syntax directive

The first line of the Dockerfile must be:

```dockerfile
# syntax=docker/dockerfile:1
```

This enables BuildKit features like cache mounts and `COPY --link`.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall