Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks.

MITAuto-check: notesDevOps & Cloud

Install Docker

skills CLI
$ npx skills add TheDecipherist/claude-code-mastery-project-starter-kit --skill docker -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install TheDecipherist/claude-code-mastery-project-starter-kit docker --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/docker .claude/skills/docker && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
docker
GitHub stars
338
Token cost
~1.6k tokens
SKILL.md length
769 words
Files
1
Skills in repo
24
Repo updated
First seen
Licence
MIT

At a glance

Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks.

  • Editing a Dockerfile
  • SKILL.md covers Dockerfile, Compose and Swarm and Secrets and config
  • Calls docker, apt-get and sh
  • A docker-compose / compose.yaml

What it does

Docker is an agent skill from TheDecipherist/claude-code-mastery-project-starter-kit. Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks. Use whenever creating or editing a Dockerfile, a docker-compose / compose.yaml, or a stack file, or building and optimizing an image. Fixes the handful of things Claude reliably gets wrong: multi-stage builds, layer-cache ordering, exec-form ENTRYPOINT for correct signals and exit codes, init:true, keeping secrets and env out of the image, non-root users, and healthchecks. From production, not defaults.

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud, covering Containers. It works with Docker. The repository describes itself as: The definitive starting point for Claude Code projects. Based on Claude Code Mastery Guides V1-V5. The licence is MIT.

When your agent uses it

  • Editing a Dockerfile
  • A docker-compose / compose.yaml
  • Building and optimizing an image

Example prompts

  • “/docker”

Requirements

  • Docker

What it can do on your machine

Read from SKILL.md and the folder at commit 61fbb99. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • docker
    • apt-get
    • sh

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use docker, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Docker loads about 1.6k tokens when it runs. Until then it costs about 126 tokens; SKILL.md has 769 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~126
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:42
    ore`.** Exclude `node_modules`, `.git`, `.env`, `dist`, and local junk. Without it the whole directory ships as build co
  • NoteMentions a .env fileSKILL.md:60
    ile working across environments through `.env`.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from TheDecipherist/claude-code-mastery-project-starter-kit at commit 61fbb99, republished under its MIT licence (© TheDecipherist). 769 words, ~1,561 tokens.

Download SKILL.mdSave it as .claude/skills/docker/SKILL.md (or your agent's skills folder).
name
docker
description
Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks. Use whenever creating or editing a Dockerfile, a docker-compose / compose.yaml, or a stack file, or building and optimizing an image. Fixes the handful of things Claude reliably gets wrong: multi-stage builds, layer-cache ordering, exec-form ENTRYPOINT for correct signals and exit codes, init:true, keeping secrets and env out of the image, non-root users, and healthchecks. From production, not defaults.
when_to_use
- Writing or editing a Dockerfile, a Compose file, or a Swarm stack file - Building, slimming, or speeding up an image - Debugging containers that won't stop…

Docker: Production Image and Compose Rules

From production, not defaults. Claude's Dockerfiles tend to be wrong in the same few ways. Fix them here.

Dockerfile

  • Multi-stage builds, always. Build in a stage that has the compilers and dev dependencies, then COPY --from=build only the artifacts into a slim runtime stage. The runtime image carries no build tools, which cuts size hard (a real build went from ~2GB to ~200MB) and removes a pile of CVEs.
dockerfile
FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
ENTRYPOINT ["node", "dist/server.js"]
  • Order layers by how often they change: stable first, source last. Docker caches each layer and rebuilds every layer after the first one whose inputs changed. So copy the dependency manifest and install deps BEFORE copying source: COPY package*.json ./ then RUN npm ci then COPY . .. Copy source first and a one-line code change reinstalls every dependency, every build.

  • The runtime command is ENTRYPOINT/CMD in exec form, never RUN. RUN executes at build time; the container's process belongs in ENTRYPOINT ["node","server.js"] (a JSON array). Use exec form, not shell form (ENTRYPOINT node server.js): shell form runs your app under /bin/sh -c, so sh is PID 1, it swallows SIGTERM, and your app never shuts down gracefully (Docker waits out the grace period then SIGKILLs it) and its exit code is lost. Exec form makes your process PID 1 so signals and exit codes propagate. ENTRYPOINT for the executable, CMD for default args.

  • Pin base image versions. FROM node:22.3.0-slim, not node:latest. latest makes builds non-reproducible and shifts under you silently. Pin a tag (or a digest for full reproducibility), and expose it as an ARG so it's easy to bump deliberately.

  • Add a .dockerignore. Exclude node_modules, .git, .env, dist, and local junk. Without it the whole directory ships as build context (slow), busts the cache on unrelated changes, and can bake a stale node_modules or a secret file into the image.

  • Run as non-root. Containers run as root by default. Add a USER (for example USER node) before the entrypoint so a container escape isn't root on the host.

  • Add a HEALTHCHECK. Swarm and Compose use it to know a container is actually ready, which is what makes rolling updates and automatic rollback work. Without it, "running" only means the process started, not that it serves traffic.

  • Combine and clean in one RUN. apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/* in a single layer. A separate update layer goes stale behind the cache, and the cleanup only shrinks the image if it happens in the same layer that added the files.

Show full SKILL.md (354 more words)Show less

Compose and Swarm

  • init: true on every service. The one always missed. It runs a tiny init (tini) as PID 1 that forwards signals to your process and reaps zombie children. Without it, signal handling and zombie reaping become your app's problem and docker stop often hangs to the timeout. Pair it with an exec-form ENTRYPOINT.

  • Set resource limits AND reservations. Reservations make the scheduler place the container only where the resources exist; limits cap it so a runaway container can't take down the node. Both, not one.

  • Configure rolling updates and rollback. update_config with parallelism: 1, a delay, order: stop-first (or start-first for blue-green), and failure_action: rollback. Combined with a HEALTHCHECK, a bad deploy rolls itself back instead of taking the service down.

  • Reference services by name, never by IP. Container IPs change on every restart, scale, and update. Use the service name and let Docker DNS resolve it (backend-service:8080). A hardcoded IP is a guaranteed future outage.

  • Substitute env with defaults. replicas: ${NGINX_REPLICAS:-2} and image: registry/app:${BUILD_VERSION:-latest} keep one file working across environments through .env.

Secrets and config

  • Never bake secrets into the image. ARG and ENV values are stored in image layers and show up in docker history, so a secret written into the Dockerfile is a leaked secret. Use BuildKit build secrets (RUN --mount=type=secret,id=...) for build time, and Docker secrets (mounted at /run/secrets/<name>) or runtime env for run time. Docker secrets are encrypted at rest, never appear in docker inspect, and are scoped to the services that mount them.

  • Secrets for sensitive, configs for the rest. Docker secret for certs, keys, and passwords (encrypted); Docker config for non-sensitive files like an IP blocklist (not encrypted, but versioned and injected the same way). Neither goes in the image, both are injected at deploy.

  • Log to stdout/stderr, not to files inside the container. Write to /dev/stdout and /dev/stderr so Docker's logging driver and your aggregator collect them. Logging to a file inside the container hides the output and fills the writable layer.


This skill is built to grow. Add a rule when a real Dockerfile or stack failure has a stable, defensible fix.

© TheDecipherist, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/docker of TheDecipherist/claude-code-mastery-project-starter-kit.

Open the folder on GitHubat commit 61fbb99

Compare with similar skills

Docker next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Docker compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Docker this skillTheDecipherist/claude-code-mastery-project-starter-kit338—~1.6kAutomated safety check: NotesMIT
Iron Proxy Gateway for NanoClawnanocoai/nanoclaw31k—~4.6kAutomated safety check: NotesMIT
GreptimeDB Dev Docker ImageGreptimeTeam/greptimedb6.7k—~4kAutomated safety check: NotesApache-2.0
Senior DevOps Toolkitmaslennikov-ig/claude-code-orchestrator-kit2596 repos~1.1kAutomated safety check: NotesCustom licence
LangBot Deployment Guidelangbot-app/LangBot18k—~1.2kAutomated safety check: NotesApache-2.0
Build Openshell Mxc WindowsNVIDIA/OpenShell15k—~4.9kAutomated safety check: PassApache-2.0

Similar skills

  • Installs or refreshes Iron Proxy and its Iron Control web console for NanoClaw, with a local Docker setup, database, credentials and a human approval bridge.

    31k GitHub stars~4.6k tokensUpdated yesterday
    DevOps & CloudAuto-check: notes
  • GreptimeDB Dev Docker Image

    GreptimeTeam/greptimedb

    Packages a locally built GreptimeDB debug binary into a development-only Docker image for local-cluster testing, with an optional push to a dev registry.

    6.7k GitHub stars~4k tokensUpdated 2 days ago
    DevOps & CloudAuto-check: notes
  • Senior DevOps Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive DevOps skill for CI/CD, infrastructure automation, containerization, and cloud platforms (AWS, GCP, Azure). Includes pipeline setup…

    259 GitHub starsUsed in 6 repos~1.1k tokens
    DevOps & CloudAuto-check: notes
  • LangBot Deployment Guide

    langbot-app/LangBot

    Deploys and configures a LangBot instance with Docker Compose or Kubernetes, covering config.yaml, the Box sandbox runtime, the plugin runtime and the global API key.

    18k GitHub stars~1.2k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Official

    Maintain and validate OpenShell's build-only Windows MSVC lane for x64 and ARM64.

    15k GitHub stars~4.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Omnigent Docker Compose Deploy

    omnigent-ai/omnigent

    Brings up the Omnigent server and Postgres as a Docker compose stack on any Docker host, and covers the Dockerfile's runtime and host build targets for extending it to a new platform.

    11k GitHub stars~1.3k tokensUpdated today
    DevOps & CloudAuto-check: notes

More from TheDecipherist/claude-code-mastery-project-starter-kit

All 24 skills in this repo
  • Create Service

    TheDecipherist/claude-code-mastery-project-starter-kit

    Scaffold a new microservice that follows the project's server/handlers/adapters architecture.

    338 GitHub stars~1.8k tokensUpdated 3 mo ago
    Auto-check: notes
  • CSS Structure

    TheDecipherist/claude-code-mastery-project-starter-kit

    Where CSS should live. An agent skill from TheDecipherist/claude-code-mastery-project-starter-kit.

    338 GitHub stars~1k tokensUpdated 3 mo ago
    Auto-check passed
  • Docker Swarm

    TheDecipherist/claude-code-mastery-project-starter-kit

    Production Docker Swarm deployment rules: what changes when a compose file goes from a single node to a multi-node Swarm.

    338 GitHub stars~1.8k tokensUpdated 3 mo ago
    Auto-check passed
  • Mongodb Backups

    TheDecipherist/claude-code-mastery-project-starter-kit

    Production MongoDB backup and restore practices that the documentation gets wrong.

    338 GitHub stars~1.3k tokensUpdated 3 mo ago
    Auto-check passed
  • Mongodb Replica Sets

    TheDecipherist/claude-code-mastery-project-starter-kit

    Production MongoDB replica-set operation: topology, durability, host tuning, and the container-specific gotchas Claude gets wrong.

    338 GitHub stars~1.6k tokensUpdated 3 mo ago
    Auto-check passed
  • Nginx

    TheDecipherist/claude-code-mastery-project-starter-kit

    Production NGINX configuration best practices, especially as a reverse proxy in front of containerized backends.

    338 GitHub stars~1.9k tokensUpdated 3 mo ago
    Auto-check passed

Works with

Categories

Questions about Docker

What does Docker do?

Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks. Docker is an agent skill from TheDecipherist/claude-code-mastery-project-starter-kit. Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks.

When should I use Docker?

Docker fits situations like: editing a Dockerfile; A docker-compose / compose.yaml; building and optimizing an image.

How do I install Docker in Claude Code?

Run `npx skills add TheDecipherist/claude-code-mastery-project-starter-kit --skill docker -a claude-code`. Or copy the skill folder (.claude/skills/docker in TheDecipherist/claude-code-mastery-project-starter-kit) into .claude/skills/docker in your project. Claude Code loads it when a task matches its description.

How do I install Docker in Codex?

Run `npx skills add TheDecipherist/claude-code-mastery-project-starter-kit --skill docker -a codex`. Or copy the skill folder (.claude/skills/docker in TheDecipherist/claude-code-mastery-project-starter-kit) into .agents/skills/docker in your project. Codex loads it when a task matches its description.

Can I use Docker in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add TheDecipherist/claude-code-mastery-project-starter-kit --skill docker -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/docker, .gemini/skills/docker, .github/skills/docker and .opencode/skills/docker in your project.

What does Docker need to run?

Going by SKILL.md and its folder, Docker needs the command-line tools its instructions call (docker, apt-get and sh). Our summary lists: Docker.

Does Docker access the network?

SKILL.md contains no URLs. Its commands use docker, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Docker safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Docker use?

Docker is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Docker use?

About 1.6k tokens (SKILL.md is roughly 6.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Docker?

Skills that share tags, products or a category with Docker: Iron Proxy Gateway for NanoClaw (nanocoai/nanoclaw, 31k stars), GreptimeDB Dev Docker Image (GreptimeTeam/greptimedb, 6.7k stars), Senior DevOps Toolkit (maslennikov-ig/claude-code-orchestrator-kit, 259 stars) and LangBot Deployment Guide (langbot-app/LangBot, 18k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Docker?

TheDecipherist (a GitHub user) maintains it in TheDecipherist/claude-code-mastery-project-starter-kit, which has 338 GitHub stars. The repository holds 24 skills in this directory. The repository was last updated on June 29, 2026.

Source: TheDecipherist/claude-code-mastery-project-starter-kit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.