---
slug: "claude-code-docker-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/wrsmith108/claude-code-docker-skill@main/README.md"
repo: "https://github.com/wrsmith108/claude-code-docker-skill"
source_file: "README.md"
branch: "main"
---
# Claude Code Docker Skill — Template Edition

> **Template-based** Docker skill for Claude Code. Customize with your project-specific placeholders, then version and distribute.

## When to Use This Repo

Use this repo if you want to:

- **Create a project-specific Docker skill** with hardcoded container names and paths
- **Version your skill** with semantic versioning (package.json, CHANGELOG)
- **Distribute a customized skill** to your team or organization

**Looking for the standard skill that auto-discovers containers?** See [docker-claude-skill](https://github.com/wrsmith108/docker-claude-skill) instead.

## How It Works

This skill uses **placeholder variables** that you replace with your project's values:

| Placeholder | Replace With |
|-------------|--------------|
| `<project-name>` | Your docker-compose service name |
| `<project-name>-dev-1` | Your container name |
| `3000` | Your application's port |
| `/path/to/your/project` | Absolute path to your project |

After customization, your skill contains hardcoded values for fast, reliable execution.

## Installation

### Option A: Claude Plugin

```bash
claude plugin add github:wrsmith108/claude-code-docker-skill
```

### Option B: Manual

```bash
mkdir -p ~/.claude/skills/docker
curl -o ~/.claude/skills/docker/SKILL.md \
  https://raw.githubusercontent.com/wrsmith108/claude-code-docker-skill/main/skills/docker/SKILL.md
```

### Configure for Your Project

Edit `~/.claude/skills/docker/SKILL.md` and replace all placeholders:

```bash
# Example: Replace for a project called "my-app" on port 8080
sed -i '' 's/<project-name>/my-app/g' ~/.claude/skills/docker/SKILL.md
sed -i '' 's/3000/8080/g' ~/.claude/skills/docker/SKILL.md
sed -i '' 's|/path/to/your/project|/Users/me/projects/my-app|g' ~/.claude/skills/docker/SKILL.md
```

## Project Setup

Your project needs Docker configuration files:

```
your-project/
├── Dockerfile           # Production build
├── Dockerfile.dev       # Development with hot reload
├── docker-compose.yml   # Container orchestration
└── .dockerignore        # Exclude node_modules, .git, etc.
```

Sample files are included at the bottom of `SKILL.md`.

## Comparison with docker-claude-skill

| Feature | This Repo (Template) | docker-claude-skill (Standard) |
|---------|---------------------|-------------------------------|
| **Approach** | Placeholders you customize | Auto-discovers containers |
| **Setup** | One-time configuration | Works immediately |
| **Performance** | Faster (hardcoded values) | Slightly slower (discovery) |
| **Multi-project** | One skill per project | Single skill for all projects |
| **Versioning** | package.json, CHANGELOG | Plugin manifest only |
| **Best for** | Teams, single-project devs | Multi-project devs, quick start |

## Usage

### Start Development Container

```bash
cd /path/to/your/project
docker-compose --profile dev up dev -d
```

### Run Commands in Container

```bash
docker exec -it <project-name>-dev-1 npm install express
docker exec -it <project-name>-dev-1 npm test
docker exec -it <project-name>-dev-1 npm run build
```

### Stop Container

```bash
docker-compose --profile dev down
```

## How the Skill Works

When Claude Code detects npm/node commands:

```
┌─────────────────────────────────────┐
│  Claude Code receives: npm install  │
└─────────────────┬───────────────────┘
                  ▼
┌─────────────────────────────────────┐
│  PRE-FLIGHT CHECK                   │
│  docker ps --filter "name=..."      │
└─────────────────┬───────────────────┘
                  ▼
         ┌───────────────┐
         │  Running?     │
         └───────┬───────┘
           Yes   │   No
            ▼    │    ▼
┌──────────────┐ │ ┌──────────────────────┐
│ docker exec  │ │ │ docker-compose up -d │
│ npm install  │ │ │ (then docker exec)   │
└──────────────┘ │ └──────────────────────┘
                 ▼
         ┌───────────────┐
         │   Complete    │
         └───────────────┘
```

## What Runs Where

| Operation | Location | Why |
|-----------|----------|-----|
| `npm install` | Container | Packages stay isolated |
| `npm test` | Container | Consistent test environment |
| `npm run build` | Container | Same Node version as prod |
| `npm run dev` | Container | Already running via compose |
| `git` commands | Host | Manages files on host |
| File editing | Host | Volume mount syncs changes |

## Troubleshooting

### Container Won't Start

```bash
docker logs <project-name>-dev-1
docker-compose --profile dev down
docker-compose --profile dev build --no-cache dev
docker-compose --profile dev up dev -d
```

### Port Already in Use

```bash
lsof -i :3000
# Kill the process or change port in docker-compose.yml
```

### Module Not Found

```bash
docker-compose --profile dev down
docker-compose --profile dev build --no-cache dev
docker-compose --profile dev up dev -d
```

## Related Skills

- [docker-claude-skill](https://github.com/wrsmith108/docker-claude-skill) — Standard version with auto-discovery
- [clerk-claude-skill](https://github.com/wrsmith108/clerk-claude-skill) — Authentication patterns
- [linear-claude-skill](https://github.com/wrsmith108/linear-claude-skill) — Issue management

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.