# Dockerfile Standard

> Use when the user asks to write, edit, review, migrate, or optimize a Dockerfile, .dockerignore, or container image build.

- Skill: `painhardcore/dockerfile-standard` (Agent Skill, multi-file: 29 files)
- Install (CLI): `npx skillmds@latest add painhardcore/dockerfile-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/painhardcore/dockerfile-standard/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: painhardcore (https://skillmd.com/u/painhardcore)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/painhardcore/dockerfile-standard

---


# dockerfile-standard

Secure, cache-efficient Dockerfiles adapted to the project in front of you. Not a template dump.

## Scope

Not here: Compose topology (`compose-standard`), Go layout and golangci (`go-project-standard`), Make target names (`makefile-standard`), when CI builds an image (`ci-standard`, though the Dockerfile content is still yours). K8s, registries, and runtime secret distribution are out of scope.

## Workflow

### 1. Inspect the repository

Inventory before writing: languages, entrypoints, manifests and lockfiles, CGO and native deps, CA and timezone needs, writable paths, ports, health and shutdown behavior, existing Dockerfiles and ignores, Compose, CI, Make, architectures, registry and tags.

Say where you are uncertain.

### 2. Apply profile and standard

Read [`references/rules.yaml`](references/rules.yaml), the source of truth for rule IDs. Then:

- Full rules: [`references/dockerfile-standard.md`](references/dockerfile-standard.md)
- [Security](references/security.md), [caching](references/caching.md), [reproducibility](references/reproducibility.md)
- Language profiles: [Go](references/profiles/go.md), [Node](references/profiles/node.md)

Greenfield: adapt a template from [`assets/`](assets/) and replace every `Adapt…` marker. Never ship an unfinished placeholder.

Migrate: [`references/migration-guide.md`](references/migration-guide.md), incrementally, measuring size and behavior before and after.

### 3. YAGNI

Nothing here is unconditional, and none of it goes in without evidence: Alpine, scratch, or distroless; `HEALTHCHECK`; every architecture; pinning every distro package; one mega-`RUN`; stripping every shell; `COPY --link`; maximum provenance on a local build.

### 4. Validate

```bash
python3 scripts/validate_dockerfile.py /path/to/Dockerfile
# image checks need Docker; smoke is opt-in:
bash scripts/validate_image.sh IMAGE_REF
bash scripts/validate_image.sh IMAGE_REF --smoke --read-only --cap-drop
```

Prefer `docker build --check .` where supported. Errors = fix. Warnings = human review. A static check is not proof of runtime security.

Validator logic is hardcoded today; the `checks:` blocks in `rules.yaml` are illustrative, not executed.

### 5. Report

- Runtime base and why it fits this project
- Stages before and after
- Image size before and after, **measured**, or say plainly that you did not measure it
- Secrets handling, runtime user, writable paths
- Multi-platform, or why single-platform
- Validations run, and which you could not run
- Exceptions taken and warnings left for review

Skip a line that has nothing to say rather than writing "not applicable".

## Hard rules

- **Never claim faster or smaller without a measurement.**
- `# syntax=docker/dockerfile:1` unless a documented labs feature is required.
- Trusted, versioned bases. No floating `latest`, no unqualified `FROM node`.
- Secrets via BuildKit secret or SSH mounts. **Never** in `ARG`, `ENV`, or a `COPY` of credentials.
- Production final stage runs as a non-root `USER` unless excepted.
- Exec-form `ENTRYPOINT` and `CMD`. Entrypoint scripts end in `exec`.
- Absolute `WORKDIR`.
- A `.dockerignore` for any non-trivial context.
- Apps must not depend on this repo at image-build time.

## Exceptions

```dockerfile
# dockerfile-standard: except <rule-id> — <reason>
```

Every ignored MUST needs an exception line with a reason. An ignored SHOULD needs a brief rationale when it is not obvious.