antongulin/opencode-skill-creator/docker-compose-helper

Docker Compose Helper

Help users create, review, and repair Docker Compose setups with the smallest working change that fits their local development workflow.

Workflow

1. Identify the user's goal:

• creating a new compose file
• adding or changing a service
• debugging startup, networking, volume, or environment issues
• translating a docker run command into compose

1. Inspect existing files before editing:

• compose.yaml
• compose.yml
• docker-compose.yaml
• docker-compose.yml
• .env
• Dockerfiles referenced by build

1. Prefer Docker Compose v2 syntax:

• omit the obsolete top-level version
• use compose.yaml if creating a new file
• keep service names lowercase and stable

1. Make the smallest useful change. Do not add orchestration, custom networks,

or named volumes unless the service needs them.

Compose Defaults

• Use explicit image tags instead of latest when a stable tag is obvious.
• Use named volumes for database state.
• Use bind mounts for application source during local development.
• Put secrets and machine-specific values in .env, not directly in YAML.
• Add depends_on only for startup ordering; add healthcheck when readiness

actually matters.

• Expose only the host ports the user needs.

Debugging Checklist

When debugging, check these in order:

1. YAML validity and indentation.
2. Whether the service name, image, build context, and Dockerfile path exist.
3. Port conflicts between host ports and already-running services.
4. Volume paths and whether a bind mount hides files built into the image.
5. Environment variable names, .env loading, and missing required values.
6. Container-to-container networking: services should use service names as DNS

hosts, not localhost.

1. Readiness problems: add a healthcheck and condition only when the dependent

service truly must wait.

Output

When editing files, show the changed compose snippet or file path and explain the reason for each non-obvious setting in one short sentence.