docker-optimize
Skill1 starsChanged 4 days agoMITView on GitHub
Design, review and improve Dockerfiles, container images, Compose stacks and container builds so they are fast, small, repeatable and safe in production - layer order, multi-stage builds, cache reuse, non-root users, real health checks, pinned base images, lean build contexts, and containers for AI model runtimes and MCP servers. Use when writing or fixing a Dockerfile or compose.yml, when an image is too big, a build is slow or rebuilds everything, a container runs as root or has no health check, or when containerizing a service.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agents-mdSkill
- app-iconSkill
- buildSkill
- cloneSkill
- debugSkill
- design-systemSkill
- improve-loopSkill
- mac-appSkill
- mac-designSkill
- product-briefSkill
- quality-barSkill
- refactorSkill
- researchSkill
- reviewSkill
- start-hereSkill
- stop-overthinkingSkill
- ui-directorSkill
- user-storiesSkill
- ux-designSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Read the Dockerfile, .dockerignore, compose.yml / docker-compose.yml, the CI workflow that builds the image, the lockfiles, and how the app …
- Very specific: line 32
Use a multi-stage build whenever the final image does not need compilers, package managers or the source tree.
- Distinctive: line 38
Run as a non-root user, with an exec-form entrypoint, explicit ports, no secrets in any layer, and a health check that proves the service …
- Distinctive: line 49
When CI is slow, check whether it builds cache-cold, what keeps invalidating layers, and whether a persistent builder or a registry cache …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Docker optimize
The outcome: a container setup that builds fast on a small change, ships only what runs, runs as a non-root user, says truthfully when it is healthy, and builds the same image again next month. Delivered as a working Dockerfile or Compose change, with numbers before and after, not a list of advice.
1. Read before you change
- Name the workload: a single service, a static site, a compiled service, a monorepo, an API plus worker, a local model runtime, an MCP server, or a multi-service Compose stack.
- Read the
Dockerfile,.dockerignore,compose.yml/docker-compose.yml, the CI workflow that builds the image, the lockfiles, and how the app starts and reports health. - Measure today: image size (
docker image ls), the layers (docker history), a cold build and a warm build after a one-line source change, the build context size, and the user the container runs as. These are the numbers you will beat.
2. Fix the build order first
Copy what changes least first and what changes most last: OS packages, then dependency manifests and lockfiles, then the dependency install, then the source, then the build. A one-line source change must not reinstall dependencies. Details in dockerfile.md.
3. Ship only what runs
Use a multi-stage build whenever the final image does not need compilers, package managers or
the source tree. Copy only the built artifacts into a small runtime stage. Keep the build
context lean with .dockerignore.
4. Harden the runtime
Run as a non-root user, with an exec-form entrypoint, explicit ports, no secrets in any layer, and a health check that proves the service can do its job, not just that the process is alive. Details in security.md.
5. Make it repeatable
Choose the base image on purpose and pin it by digest when stability matters. Install dependencies from the lockfile only. Keep build-time and runtime concerns apart.
6. Make delivery fast
When CI is slow, check whether it builds cache-cold, what keeps invalidating layers, and whether a persistent builder or a registry cache would help. Fix the Dockerfile before reaching for new tooling. For Compose stacks, model runtimes and MCP servers, see architecture.md.
7. Prove it
Build again and compare with step 1: image size, cold and warm build time, the runtime user, the health check passing (and failing when the dependency it checks is down). Run the app's tests against the new image. If a number is unknown, say so; never invent one.
Never
COPY . .before the dependency install.- Compilers, package managers, shells or debug tools in a production image without a reason.
latestor a moving major tag where the build has to be repeatable.- Secrets in
ARG,ENVor any layer; pass them as build secrets or at runtime. - A health check that only checks the process or the open port.
- Root in the final image without a written reason.
- A bigger change than the problem needs: a layer fix before a new build system.
Done when
The new setup builds and runs, the before and after numbers are reported, the container runs as a non-root user with a health check that tests real readiness, the base image is chosen on purpose, and any tradeoff (size against debuggability, pinning against upkeep) is named in a line.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

