docker-debugger — Claude Code skill for Docker troubleshooting
The docker-debugger skill helps investigate container, Dockerfile, networking, and docker-compose problems. Use it when a build fails or a container behaves unexpectedly.
MIT 314 installs ★ 440 updated 2026-10-20
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a claude-codeWhat docker-debugger does
The skill sorts Docker problems into build, runtime, networking, or performance issues. It then suggests diagnostic commands, log and error analysis, and fixes. For a container that exits, it checks the exit code and recent logs; for network trouble, it examines Docker networks and container settings.
Its Dockerfile guidance covers multi-stage builds, copying dependency files early for caching, and running as a non-root user. For docker-compose, it shows how to open an interactive shell, override a service command, and inspect service logs. Some examples use Node.js and npm, so adapt those snippets to your project's build setup.
The skill guides the investigation rather than running fixes on its own. Give the agent container details and logs to work from.
What it helps with
- find why a container exits
- diagnose a failed Dockerfile build
- check connectivity between containers
- fix permissions on a mounted volume
- debug a docker-compose service
Example prompts for the agent
- Inspect the logs for container
weband find why it exited. - Review this Dockerfile and explain why its build fails.
- Help me debug networking and volume access in
docker-compose.yml.
How to install docker-debugger
1Skills CLI (Vercel)
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a claude-code2Manually: put the files in place
~/.claude/skills/docker-debugger/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/docker-debugger/
1Skills CLI (Vercel)
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a codex2Manually: put the files in place
.agents/skills/docker-debugger/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a cursor2Manually: put the files in place
.cursor/skills/docker-debugger/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OneWave-AI/claude-skills docker-debugger2Manually: put the files in place
.github/skills/docker-debugger/SKILL.md1Skills CLI (Vercel)
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a gemini-cli2Platform CLI
gemini skills install https://github.com/OneWave-AI/claude-skills --path docker-debuggerManually: put the files in place
.devin/skills/docker-debugger/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about docker-debugger
How do I install docker-debugger in Claude Code?
Run npx skills add OneWave-AI/claude-skills --skill docker-debugger -a claude-code, then use the skill at ~/.claude/skills/docker-debugger/SKILL.md.
What does docker-debugger do?
It helps investigate failed builds, container exits, network errors, and volume permission problems. It also provides Dockerfile and docker-compose debugging guidance.
Which Docker commands does the skill use for diagnostics?
Its examples include docker ps -a, docker logs, docker inspect, and docker stats, along with commands for inspecting networks and image history.
Source text
SKILL.md · MIT
---
name: docker-debugger
description: Debug Docker containers, fix Dockerfile issues, optimize images, and troubleshoot docker-compose. Use when having Docker problems, container issues, or optimizing Docker builds.
---
# Docker Debugger
## Instructions
When debugging Docker issues:
1. **Identify the problem type**: Build, runtime, networking, or performance
2. **Gather information** using diagnostic commands
3. **Analyze logs and errors**
4. **Apply fixes**
## Diagnostic Commands
```bash
# Check running containers
docker ps -a
# View container logs
docker logs <container_id> --tail 100 -f
# Inspect container
docker inspect <container_id>
# Check resource usage
docker stats
# View container processes
docker top <container_id>
# Execute shell in running container
docker exec -it <container_id> /bin/sh
# Check Docker disk usage
docker system df
# View build history
docker history <image_name>
```
## Common Issues & Solutions
### 1. Container exits immediately
```bash
# Check exit code
docker inspect <container_id> --format='{{.State.ExitCode}}'
# View last logs
docker logs <container_id>
```
**Fixes**:
- Ensure CMD/ENTRYPOINT runs a foreground process
- Check for missing dependencies
- Verify environment variables
### 2. Build fails
```dockerfile
# Use multi-stage builds for smaller images
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
```
### 3. Networking issues
```bash
# List networks
docker network ls
# Inspect network
docker network inspect <network_name>
# Check container IP
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container>
```
### 4. Volume permission issues
```dockerfile
# Create non-root user
RUN addgroup -g 1001 -S appgroup && \
adduser -u 1001 -S appuser -G appgroup
# Set ownership
COPY --chown=appuser:appgroup . .
USER appuser
```
## Dockerfile Best Practices
```dockerfile
# 1. Use specific tags, not :latest
FROM node:20.10-alpine
# 2. Set working directory
WORKDIR /app
# 3. Copy dependency files first (better caching)
COPY package*.json ./
RUN npm ci --only=production
# 4. Copy source after dependencies
COPY . .
# 5. Use non-root user
USER node
# 6. Set proper labels
LABEL maintainer="[email protected]"
LABEL version="1.0"
# 7. Use HEALTHCHECK
HEALTHCHECK --interval=30s --timeout=3s \
CMD wget -q --spider http://localhost:3000/health || exit 1
# 8. Expose ports
EXPOSE 3000
# 9. Use exec form for CMD
CMD ["node", "server.js"]
```
## docker-compose Debugging
```yaml
# docker-compose.yml
services:
app:
build:
context: .
dockerfile: Dockerfile
# Add for debugging
stdin_open: true
tty: true
# Override command for debugging
command: /bin/sh
volumes:
- .:/app
environment:
- DEBUG=true
```
```bash
# Rebuild without cache
docker-compose build --no-cache
# View logs
docker-compose logs -f app
# Restart single service
docker-compose restart app
```
© OneWave-AI · MIT · OneWave-AI/claude-skills