Dockerfile Doctor

What it does

Smaller, faster, safer images.

Your agent loads it when the user writes or fixes a Dockerfile. It carries 5 rules and reads a profile.md with your details before it starts, so the output matches your brand and project.

SKILL.md, first 40 lines

---
name: dockerfile-doctor
description: "Use when the user says 'review my Dockerfile', 'my docker image is huge', 'docker build is slow', 'optimize this Dockerfile', 'make this image production ready', 'add a multi-stage build', 'run as non-root', or 'why is the cache busting'. Audits a Dockerfile and .dockerignore, rewrites them with multi-stage builds, lockfile-first layer order, pinned bases, a non-root user, no secrets in layers, a healthcheck and correct signal handling, and reports image size and build time before and after. Reads profile.md for cloud, runtime, CI and environments; per-language templates and findings checklist in templates.md."
---

# Dockerfile Doctor

Audit a Dockerfile the way a platform engineer would: find what makes the image big, slow to build, insecure or hard to stop, fix it, and prove the improvement with numbers. Do not rewrite for style; every change must buy size, build time, safety or reproducibility.

## Before you start

Read `profile.md` in this folder:

| profile.md line | Use |
|---|---|
| **Cloud** | Registry and platform quirks (ECR, Artifact Registry, ACR, Fly, Render) and the CPU architecture to build for. |
| **Runtime** | Kubernetes: add probes in the manifest, not only `HEALTHCHECK`, and set `runAsNonRoot`. Containers (ECS / Cloud Run): the platform health check replaces `HEALTHCHECK`; listen on `$PORT` for Cloud Run. Serverless: image must match the Lambda base and handler contract. VMs: keep `HEALTHCHECK`. |
| **CI** | Where the build runs; use its cache backend (`type=gha`, registry cache) in the build command you suggest. |
| **Environments** | Which environments build the image; one image per commit, configuration injected at run time, never baked per environment. |

If a line says "not set", ask once, write it into profile.md, continue. Open `templates.md` for the language template and the findings checklist.

## Workflow

1. **Read everything the build reads.** The Dockerfile, `.dockerignore`, the lockfile and manifest, any compose file or CI build step. Identify language, framework, entrypoint, port and what the app needs at run time versus build time.
2. **Measure the baseline.** If Docker is available and the user agrees to a local build: `docker build -t app:before .` twice (cold with `--no-cache`, then warm after touching one source file), `docker image ls app:before`, `docker history app:before`. Record size and seconds. If you cannot build, say "not measured" and estimate nothing.
3. **Audit** against the findings checklist in `templates.md`. Label each finding high, medium or low (table below).
4. **Rewrite** with the smallest set of changes that fixes the highs and mediums. Keep the app's existing behaviour: same port, same command, same env var names.
5. **Add or fix `.dockerignore`** before touching layers; a missing one is the most common cause of cache busting and leaked files.
6. **Rebuild and compare.** Same two builds, same machine. Report size and times as before, after, delta. Run the container and confirm it starts, answers its health check and stops within seconds on `docker stop`.
7. **Hand over** the diff and the commands. Do not push, tag or publish an image, and do not touch a registry or cluster without asking.

## Severity

| Severity | Examples |
|---|---|
| High | Secret or token in a layer or `ARG`; runs as root with no reason; `latest` or unpinned base in production; `curl` piped to a shell during build; whole repo copied before dependency install on every change |
| Medium | No multi-stage (compilers and dev dependencies shipped); shell-form `CMD` so signals are lost; no `.dockerignore`; no healthcheck; non-reproducible install (`npm install`, unpinned `pip`) |
| Low | Many small `RUN` layers; missing `--no-install-recommends`; apt/apk caches left behind; no `LABEL`s |

Install

One command, in your project folder. It detects your agent; add --agent all for every agent.

npx proskills-cli add dockerfile-doctor

Or copy the skill folder (the one holding SKILL.md) into the directory your agent reads, then restart it or start a new session.

More from DevOps & Cloud

• CI Pipeline Builder$12Fast, locked-down CI. GitHub Actions first.
• Terraform Reviewer$12Reads the plan before it destroys something.
• K8s Manifest Review$9Probes, limits and security contexts done right.