Docker Container Debugger skill for Claude and Codex
Gets a crashing, hanging, or misbehaving container diagnosed with an ordered command sequence: what to run, why, and what a healthy versus faulty result looks…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a running container crashes, restarts, hangs, or cannot reach its dependencies and the user needs the commands to find out why. Do not use for assessing an image for vulnerabilities before deployment, or shrinking an image. Related topics: coding, docker.
What it will ask you for
- Container ID or name (free text, e.g. "api-worker-1")
- Problem symptom (longer free text)
- Base image OS (choose one: Alpine, Ubuntu, Debian, CentOS, Distroless, Other)
- Access level (choose one: root, non-root)
- Log locations to inspect (choose any: Container stdout and stderr, /var/log/app.log, /var/log/syslog, Orchestrator logs, Custom path)
- Issue timeframe (choose one: last 5 minutes, last hour, last day, unknown)
- Runtime (choose one: Docker CLI, Docker Compose, Kubernetes, ECS, Other)
How it works
- Order the checks from outside in: state and exit code, logs for the timeframe, resources and OOM, networking, filesystem and permissions, then in-container processes.
- Write each check as the exact command for the chosen runtime with its purpose, the healthy result, and what a faulty result indicates.
- Substitute tooling for minimal base images (busybox or a debug container) and remove commands the access level cannot run.
- Name the two most likely causes for the symptom and point to the step that confirms each.
What you get
A numbered Markdown list, one step each with the command, a one-line purpose, the expected healthy result, and the faulty-result interpretation, followed by the two most likely causes and their confirming steps.
What it watches out for
- Starting with docker exec when the container exits immediately; the exit code and logs answer most crashes without a shell.
- Giving bash and curl commands for an Alpine or distroless image where neither exists.
- Reading logs without --since, so the relevant error is buried under a day of healthy output.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.