learn-docker-k8s-game

What this skill does

# Learn Docker & K8s Game

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

An open-source, AI-driven interactive learning game that teaches Docker, Linux, networking, and Kubernetes through a story-driven simulation. No web app, no video courses — just you, your AI editor, a terminal, and the chaotic coffee startup NoCappuccino Inc.

---

## How It Works

The game runs entirely inside your AI editor. Markdown prompt files in this repo act as the game engine. When a user says "let's play," the AI reads `AGENTS.md` (or the editor-specific entry point), becomes "Sarah" (the mentor character), and walks the learner through real Docker/K8s scenarios using their actual terminal.

```
User says "let's play"
    → AI reads AGENTS.md + engine/rules.md + engine/narrator.md
    → AI becomes Sarah, the senior DevOps mentor
    → Story begins: Dave broke staging, fix it with containers
    → Lessons → Challenges → verify.sh → next chapter
```

---

## Installation

```bash
git clone https://github.com/ericboy0224/learn-docker-and-k8s.git
cd learn-docker-and-k8s
```

Open the directory in your AI editor, then type: **"let's play"**

### Prerequisites

| Requirement | Chapters | Notes |
|---|---|---|
| Docker | Ch 1–7 | Required |
| Docker Compose v2 | Ch 1–7 | Required |
| kubectl | Ch 6–7 | Optional |
| kind | Ch 6–7 | Optional |
| AI Editor | All | Claude Code, Cursor, Windsurf, Copilot, Cline, Codex, Gemini CLI |

### Environment Check

```bash
bash engine/environment-check.sh
```

This verifies Docker, Docker Compose, and optional Kubernetes tools are installed and running.

---

## Editor Entry Points

Each AI editor reads a different config file automatically:

| Editor | Entry File |
|---|---|
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursorrules` |
| Windsurf | `.windsurfrules` |
| Cline / Roo Code | `.clinerules` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Gemini CLI | `GEMINI.md` |
| All others | `AGENTS.md` |

The AI editor will read the appropriate file on startup and load game context from `engine/` and `curriculum/`.

---

## Game Commands

Type these naturally in your AI editor chat:

```
/play           — start or resume the game
/env-check      — verify Docker/K8s setup before starting
/progress       — view save file (.player/progress.yaml)
/hint           — progressive hint (3 levels: nudge → direction → near-answer)
/verify         — check your challenge solution
/next           — advance to next lesson or challenge
/skip-to <N>    — jump to chapter N (triggers a quiz gate)
/cleanup        — remove all learn-* Docker resources safely
```

You can also speak naturally:
- `"I'm stuck on the port mapping"`
- `"check my work"`
- `"what does -p do again?"`
- `"skip to chapter 4"`

---

## Curriculum Overview

```
Ch1 → Ch2 → Ch3 → Ch4 → Ch5 → Ch6 → Ch7
```

| Chapter | Title | Core Skills |
|---|---|---|
| 1 | 📦 It Works on My Machine | containers, images, port mapping |
| 2 | 🏋️ The 2GB Espresso | multi-stage builds, layer caching, .dockerignore |
| 3 | 💾 The Vanishing Beans | volumes, bind mounts, persistence |
| 4 | 🔌 The Silent Grinder | DNS, bridge networks, isolation |
| 5 | 🎼 The Symphony of Steam | Docker Compose, health checks, secrets |
| 6 | ⎈ The Giant Roaster | Pods, Deployments, Services, self-healing |
| 7 | 🔥 The Great Latte Leak | rolling updates, Secrets, HPA, chaos triage |

Linux fundamentals (namespaces, cgroups, mounts) and networking (DNS, NAT, subnets, iptables) are taught contextually throughout — no dedicated lecture needed.

---

## Project Structure

```
learn-docker-and-k8s/
├── AGENTS.md                        # Universal AI entry point
├── CLAUDE.md                        # Claude Code entry + skill definitions
├── GEMINI.md                        # Gemini CLI entry point
├── .cursorrules                     # Cursor entry point
├── .clinerules                      # Cline/Roo Code entry point
├── .windsurfrules                   # Windsurf entry point
├── .github/
│   └── copilot-instructions.md      # GitHub Copilot entry point
│
├── engine/
│   ├── rules.md                     # Teaching vs challenge mode rules
│   ├── narrator.md                  # Story, characters (Sarah/Dave/Marcus), tone
│   ├── validation.md                # How AI should verify challenge solutions
│   ├── environment-check.sh         # Pre-flight Docker/K8s check
│   └── cleanup.sh                   # Remove all learn-* resources
│
├── curriculum/
│   ├── ch01-containers/
│   │   ├── README.md                # Chapter story + learning objectives
│   │   ├── lessons/                 # 3 teaching lessons per chapter
│   │   ├── challenges/              # Hands-on tasks + verify.sh scripts
│   │   └── quiz.md                  # Skip-level assessment questions
│   ├── ch02-image-optimization/
│   ├── ch03-persistence/
│   ├── ch04-networking/
│   ├── ch05-compose/
│   ├── ch06-k8s-intro/
│   └── ch07-k8s-production/
│
└── .player/
    └── progress.yaml                # Save file — AI reads/writes this
```

---

## The Game Engine: Key Files

### `engine/rules.md`
Defines the two game modes:
- **Teaching mode** — AI explains concepts, answers questions freely
- **Challenge mode** — AI gives only progressive hints; never reveals the answer directly

### `engine/narrator.md`
Defines character voices and story tone:
- **Sarah** — friendly senior DevOps mentor, uses coffee metaphors
- **Dave** — CTO who breaks things and says "just restart it"
- **Marcus** — PM who sets impossible deadlines ("demo is at 3")

### `engine/validation.md`
Tells the AI how to run and interpret `verify.sh` scripts — it will execute them in the terminal and parse output to determine pass/fail.

### `.player/progress.yaml`
The save file. The AI manages this automatically:

```yaml
# .player/progress.yaml (example structure)
player:
  name: ""
  started_at: ""
current:
  chapter: 1
  lesson: 2
  challenge: 1
completed:
  chapters: []
  challenges: []
hints_used: 0
```

---

## Challenge Verification Scripts

Each challenge has a `verify.sh` that the AI runs to check the learner's work:

```bash
# curriculum/ch01-containers/challenges/verify.sh (example pattern)
#!/bin/bash
set -e

echo "🔍 Checking Chapter 1 Challenge..."

# Check container is running
if docker ps --filter "name=learn-api" --filter "status=running" | grep -q "learn-api"; then
  echo "✅ Container 'learn-api' is running"
else
  echo "❌ Container 'learn-api' not found or not running"
  exit 1
fi

# Check port mapping
if docker inspect learn-api | grep -q '"HostPort": "8080"'; then
  echo "✅ Port 8080 is mapped correctly"
else
  echo "❌ Port mapping incorrect — expected 8080:8080"
  exit 1
fi

# Check endpoint responds
if curl -sf http://localhost:8080/health > /dev/null; then
  echo "✅ API is responding on port 8080"
else
  echo "❌ API not responding — check the container logs"
  exit 1
fi

echo ""
echo "🎉 Challenge complete! Sarah is proud of you."
```

---

## Real Docker Commands Used in the Game

The game teaches these patterns through hands-on challenges:

```bash
# Ch1 — Run a container with port mapping
docker run -d --name learn-api -p 8080:8080 my-api-image

# Ch2 — Multi-stage build to reduce image size
docker build -t learn-api:optimized .
docker images learn-api  # compare sizes

# Ch3 — Named volume for persistence
docker volume create learn-beans-data
docker run -d -v learn-beans-data:/app/data --name learn-db postgres:15

# Ch3 — Bind mount for development
docker run -d -v $(pwd)/src:/app/src --name learn-dev my-app

# Ch4 — Custom bridge network
docker network create learn-coffee-net
docker run -d --network learn-coffee-net --name learn-api my-api
docker run -d --network learn-coffee-net --name learn-db postgres:15

# Ch5 — Docker Compose
docker compose up -d
docker compose ps
docker compose logs -f api
docker compose down -v

# Ch6 — Kubernetes basics
kubectl apply -f curriculum/ch06-k8s-intro/manifests/
kubectl get pods -l app=learn-api
kubectl roll