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

-it

# 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

npm install

npm run dev

npm test

npm run build

git

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

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

1. Always check container status before running commands
2. Use docker exec for ALL npm/node operations
3. Never install packages on host - always in container
4. Use node:20-slim by default - switch to alpine only if no native modules
5. Rebuild image after changing

   package.json

   or

   Dockerfile

6. Check logs when something isn't working
7. 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

docker exec <container> npm install <pkg>

docker exec <container> npm test

docker exec <container> npm run typecheck

docker exec <container> npm run build

Related Skills

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

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

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