Docker Development Skill

Execute all package installations and code execution inside Docker containers. This keeps the host machine clean and ensures consistent environments across projects.

Behavioral Classification

Type: Autonomous Execution

Directive: EXECUTE, DON'T ASK

This skill enforces Docker-first development automatically. When you request npm/node operations, commands are executed inside Docker without asking for permission.

Enforcement Behavior:

Blocks host-machine npm/node commands
Suggests or transforms commands to use docker exec
Automatically checks container status before operations

Quick Start

For new projects, see setup.md for the complete first-time setup guide.

Minimal setup:

# 1. Start container
docker compose --profile dev up -d

# 2. Verify running
docker ps --filter "name=my-project"

# 3. Run commands in container
docker exec my-project-dev-1 npm install
docker exec my-project-dev-1 npm test
docker exec my-project-dev-1 npm run build

ENFORCEMENT RULES

BLOCKED: Never Run on Host

These commands are BLOCKED on the host machine:

npm install, npm ci, npm run, npm test, npm exec
npx <anything>
yarn add, yarn install, yarn run
pnpm add, pnpm install, pnpm run
node <script>
tsx <script>
bun <script>

Why? Installing packages on the host:

Pollutes the host machine with project-specific dependencies
Creates version conflicts between projects
Makes environments non-reproducible
Can cause security issues with global packages

REQUIRED: Use docker exec

All Node.js commands MUST use this prefix:

docker exec <container-name> <command>

Note: Use docker exec WITHOUT the -it flag in Claude Code:

# Correct (works in Claude Code)
docker exec my-project-dev-1 npm run build

# Wrong (fails with "not a TTY")
docker exec -it my-project-dev-1 npm run build

Pre-Flight Check (MANDATORY)

Before running ANY npm/node command, verify the container is running.

docker ps --filter "name=<container-name>" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Expected output:

NAMES                   STATUS          PORTS
my-project-dev-1        Up X minutes    0.0.0.0:3000->3000/tcp

If container is NOT running:

cd /path/to/project
docker compose --profile dev up -d
docker ps --filter "name=<container-name>"

If container shows "Exited":

docker logs <container-name> --tail 20
docker compose --profile dev down
docker compose --profile dev up -d

Quick Reference

Check Container Status

docker ps --filter "name=<container-name>"
docker logs <container-name> --tail 50
curl -s http://localhost:<port> > /dev/null && echo "Running" || echo "Not running"

Start/Stop Containers

docker compose --profile dev up -d        # Start
docker compose --profile dev down         # Stop
docker compose --profile dev restart dev  # Restart
docker compose --profile dev up -d --build  # Rebuild

Execute Commands Inside Container

docker exec <container> npm install <package>     # Install package
docker exec <container> npm install -D <package>  # Install dev dependency
docker exec <container> npm test                  # Run tests
docker exec <container> npm run typecheck         # Type checking
docker exec <container> npm run lint              # Linting
docker exec <container> npm run build             # Build
docker exec <container> /bin/sh                   # Shell (use -it for interactive)

When to Use docker exec

| Operation | Use docker exec? | Reason | |-----------|------------------|--------| | npm install | Always | Packages install in container only | | npm run dev | No | Already running via docker-compose | | npm test | Yes | Tests run in container environment | | npm run build | Yes | Build happens in container | | git commands | No | Git runs on host (manages files) | | File editing | No | Volume mount syncs automatically | | Database migrations | Yes | Uses container's Node environment |

Container Architecture

┌─────────────────────────────────────────────────────────────┐
│  HOST (macOS/Linux/Windows)                                 │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Docker Container (my-project-dev-1)                │   │
│  │                                                     │   │
│  │  Node 20 (Slim or Alpine)                           │   │
│  │  └── node_modules/ (container-only, NOT on host)    │   │
│  │  └── Dev server (port 3000)                         │   │
│  │                                                     │   │
│  │  Volume Mounts:                                     │   │
│  │  └── .:/app (source code sync)                      │   │
│  │  └── node_modules:/app/node_modules (persist deps)  │   │
│  └─────────────────────────────────────────────────────┘   │
│                         │                                   │
│                         ▼                                   │
│                   Port mapped                               │
│                         │                                   │
│                         ▼                                   │
│              http://localhost:<port>                        │
└─────────────────────────────────────────────────────────────┘

Key Point: node_modules exists ONLY in the container. The host machine stays clean.

Volume Mount Behavior

volumes:
  - .:/app                           # Source code (synced)
  - node_modules:/app/node_modules   # Dependencies (container-only)

What this means:

Source code changes on host are immediately visible in container
node_modules/ lives in a named Docker volume, NOT on host filesystem
Hot reload works automatically
Host machine never has project dependencies installed

Troubleshooting

Container Not Running

docker ps -a --filter "name=<container-name>"
docker logs <container-name>
docker compose --profile dev up -d

Port Already in Use

lsof -i :<port>
# Kill the process or change port in docker-compose.yml

Module Not Found Errors

docker compose --profile dev down
docker compose --profile dev build --no-cache
docker compose --profile dev up -d
docker exec <container> npm install

File Changes Not Reflecting

docker inspect <container-name> | grep -A 10 "Mounts"
docker compose --profile dev restart dev

Wrong Architecture (M1/M2 Mac)

If you see platform warnings:

# Add to docker-compose.yml service
platform: linux/amd64  # or linux/arm64

Native Module Errors

See setup.md for the complete native module troubleshooting guide including:

ERR_DLOPEN_FAILED resolution
Alpine vs Slim decision tree
Rebuild instructions

Best Practices

Always check container status before running commands
Use docker exec for ALL npm/node operations
Never install packages on host - always in container
Use node:20-slim by default - switch to alpine only if no native modules
Rebuild image after changing package.json or Dockerfile
Check logs when something isn't working
Use named volumes for node_modules to persist between container restarts

Health Checks

For automated health monitoring and CI integration, see health-checks.md:

Container healthcheck configuration
Health check shell script
NPM scripts integration
Troubleshooting health failures

Integration with Claude Code

| Task | Action | |------|--------| | Install dependency | docker exec <container> npm install <pkg> | | Run tests | docker exec <container> npm test | | Check types | docker exec <container> npm run typecheck | | Build project | docker exec <container> npm run build | | Start dev server | Container already runs it via docker-compose | | Edit files | Edit directly (volume mount syncs) | | Git operations | Run on host (not in container) |

Related Skills

For complete Docker development support, use with these complementary skills:

| Skill | Purpose | |-------|---------| | docker-enforce | Automatically blocks/transforms host commands to run inside Docker | | docker-optimizer | Analyzes Dockerfiles for optimization opportunities | | docker-guard | Prevents hangs when Docker daemon is unresponsive |

docker-enforce

Provides automated enforcement of Docker-first policy:

Intercepts npm, npx, yarn, pnpm, node, tsx, bun commands
Blocks commands on host with suggestion to use docker exec
Can auto-transform commands to run inside container
Configurable allowlist for safe host commands

Install: git clone https://github.com/wrsmith108/docker-enforce.git ~/.claude/skills/docker-enforce

Reference Documentation

| Document | Contents | |----------|----------| | setup.md | First-time setup, native module troubleshooting, project configuration | | health-checks.md | Container healthchecks, monitoring scripts, NPM integration |

Changelog

v1.1.0 (2026-01-23)

Refactor: Decompose into sub-files for progressive disclosure
Extract first-time setup to setup.md
Extract health checks to health-checks.md
Add Behavioral Classification section (ADR-025)
Main SKILL.md reduced from 718 to ~320 lines

v1.0.0 (2025-01)

Initial release
Docker-first enforcement rules
Container architecture documentation
Troubleshooting guide

Last updated: January 2026