Docker Compose v2 / Compose Specification

Use this skill when creating or reviewing a Docker Compose project: local dev stacks, service dependencies, databases, queues, reverse proxies, GPUs, Docker Model Runner, develop.watch, or multi-file overrides.

This skill tracks the Compose Specification and Docker Docs as of June 2026.

Defaults for new projects

• File name: create compose.yaml, not docker-compose.yml. Docker Compose discovers compose.yaml / compose.yml before legacy docker-compose.yaml / docker-compose.yml, and current Docker docs use compose.yaml.
• Command: use docker compose (space) for Compose v2. The old docker-compose binary is legacy.
• Top-level version: omit it. version: is obsolete in the Compose Specification and does not select supported features.
• Validation: run docker compose config before saying the file is ready.
• Secrets: never hardcode secret values in YAML. Use Docker secrets, mounted files, or gitignored env files; prefer _FILE env vars when images support them.
• Images: pin tags or digests. Avoid latest except disposable demos.
• Ports: bind local-only services as 127.0.0.1:HOST:CONTAINER; do not publish databases publicly unless explicitly requested.

Authoring workflow