Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add OneWave-AI/claude-skills --skill docker-debugger -a claude-code
Open on GitHub

What 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 web and 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-code

2Manually: put the files in place

~/.claude/skills/docker-debugger/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/docker-debugger/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set185

The whole set →
sports-podcast-outline-generator sports-podcast-outline-generator builds a sports podcast episode plan: segment timing, debate topics, listener questions and ad break slots. CX Codex +1 320installs post-game-press-conference-simulator post-game-press-conference-simulator generates realistic press conference interviews for coaches and athletes. Useful for sports stories, game dialogues, or covering wins, losses, controversies, and injuries. CX Codex +1 320installs api-endpoint-scaffolder api-endpoint-scaffolder — a skill that scaffolds REST endpoints from templates for Next.js App Router and Express: Zod schemas, status codes, error handling. CX Codex +1 317installs error-boundary-creator error-boundary-creator sets up error boundaries, fallback UIs, and crash reporting for React and Next.js apps. Keeps uncaught component crashes from breaking the entire page. CX Codex +1 316installs scout scout reads the running conversation and names the skill or subagent that fits the task, with a short plan for using them together. CX Codex +1 314installs test-coverage-improver test-coverage-improver — a skill that identifies coverage gaps and generates missing tests for critical code paths. CX Codex +1 312installs env-setup-wizard env-setup-wizard structures .env files, configures Zod schema validation, and prevents secret leaks into git repositories. CX Codex +1 308installs client-proposal-generator client-proposal-generator is a Claude Code skill that turns a client brief into proposal.md with a work plan, timeline, team, pricing, and terms. It drafts a consulting proposal for a specific client. CX Codex +1 301installs

Project sponsors

Companies that keep this analytics open