dotfiles/.config/opencode/skills/docker-container-management/SKILL.md

name, description, permalink

name	description	permalink
docker-container-management	Reusable Docker container workflow for build, test, and dev tasks in containerized repos	opencode-config/skills/docker-container-management/skill

Docker Container Management

Load this skill when a repo uses Docker/docker-compose for builds, tests, or local dev, or when a task involves containerized workflows.

Core Workflow

1. Detect — look for Dockerfile, docker-compose.yml/compose.yml, or .devcontainer/ in the repo root.
2. Prefer compose — use docker compose (v2 CLI) over raw docker run when a compose file exists.
3. Ephemeral containers — default to --rm for one-off commands. Avoid leaving stopped containers behind.
4. Named volumes over bind-mounts for caches (e.g., package manager caches). Use bind-mounts only for source code.
5. No host-path writes outside the repo — all volume mounts must target paths inside the repo root or named volumes. This preserves external_directory: deny.

Path and Volume Constraints

• Mount the repo root as the container workdir: -v "$(pwd):/app" -w /app.
• Never mount host paths outside the repository (e.g., ~/.ssh, /var/run/docker.sock) unless the plan explicitly approves it with a stated reason.
• If root-owned artifacts appear after container runs, document cleanup steps (see main/knowledge/worktree-cleanup-after-docker-owned-artifacts).

Agent Guidance

• planner: Use Docker during planning for context gathering and inspection (e.g., docker compose config, docker ps, docker image ls, docker network ls, checking container health or logs). Do not run builds, installs, tests, deployments, or any implementation-level commands — those belong to builder/tester/coder.
• builder/coder: Run builds and install steps inside containers. Prefer docker compose run --rm <service> <cmd> for one-off tasks.
• tester: Run test suites inside the same container environment used by CI. Capture container exit codes as verification evidence.
• coder: When writing Dockerfiles or compose files, keep layers minimal, pin base image tags, and use multi-stage builds when the final image ships.

Red Flags

• docker run without --rm in automation scripts.
• Bind-mounting sensitive host paths (/etc, ~/.config, /var/run/docker.sock).
• Building images without a .dockerignore.
• Using latest tag for base images in production Dockerfiles.