Agent-Skills.md

Agent Skills: Dev Containers Skill

Provides expert guidance on Development Containers (devcontainers) — creating, configuring, and optimising containerised development environments using the Dev Container Specification. This skill should be used when users ask about devcontainer.json, .devcontainer setup, Dev Container Features or Templates, pre-building images, multi-container workflows, Docker-in-Docker, cloud development environments (Codespaces, DevPod), or troubleshooting container performance and permission issues.

[dockercontainersdevcontainersvscodecodespacesdevpod]
UncategorizedID: markpitt/claude-skills/devcontainers

Repository

markpitt/claude-skills
markpitt
122

Install this agent skill to your local

pnpm dlx add-skill https://github.com/markpitt/claude-skills/tree/HEAD/skills/devcontainers

Skill Files

Browse the full folder contents for devcontainers.

Download Skill

Loading file tree…

skills/devcontainers/SKILL.md

Skill Metadata

Name
devcontainers
Description
Provides expert guidance on Development Containers (devcontainers) — creating, configuring, and optimising containerised development environments using the Dev Container Specification. This skill should be used when users ask about devcontainer.json, .devcontainer setup, Dev Container Features or Templates, pre-building images, multi-container workflows, Docker-in-Docker, cloud development environments (Codespaces, DevPod), or troubleshooting container performance and permission issues.

Dev Containers Skill

Expert guidance on creating, configuring, and optimising containerised development environments using the Dev Container Specification. Covers devcontainer.json authoring, Features, Templates, performance, security, multi-container setups, and cloud environments.

Quick Reference Table

| Task | Load Resource | Key Concepts | |------|--------------|--------------| | Create or configure a devcontainer.json | references/core-concepts.md | image, build, features, lifecycle hooks, customizations | | Add tools/languages to a container | references/features-templates.md | Features, version pinning, installsAfter, Templates | | Set up multi-container or Docker-in-Docker | references/advanced-config.md | dockerComposeFile, DinD, DooD, Kubernetes, service | | Improve build/startup speed | references/performance-security.md | layer caching, named volumes, pre-built images, Virtio-fs | | Harden container security or manage secrets | references/performance-security.md | remoteUser, UID mapping, SSH forwarding, secrets | | Debug slow mounts, permission errors, credential issues | references/troubleshooting.md | UID/GID, bind mounts, SSH agent, postCreateCommand | | Integrate with Codespaces or DevPod | references/advanced-config.md | prebuilds, providers, SSH, cloud residency |

Orchestration Protocol

Phase 1 — Classify the Task

Identify which category the user's request falls into:

  • Configuration — writing or editing devcontainer.json, Dockerfiles, Compose files
  • Tooling — adding Features, authoring custom Features, or using Templates
  • Advanced — multi-container, DinD/DooD, Kubernetes, cloud environments
  • Optimisation — caching, pre-built images, named volumes, disk I/O
  • Security — non-root users, UID mapping, secrets, hardened images
  • Troubleshooting — permission errors, slow builds, SSH/GPG credential issues

Phase 2 — Load the Right Resource

Load the resource indicated in the Quick Reference Table. For complex tasks spanning multiple areas (e.g. "set up a secure multi-container environment with fast builds"), load both relevant files.

Phase 3 — Execute

Apply the guidance from the loaded resource. Use concrete examples from the resource files. For configuration tasks, produce a complete, commented devcontainer.json snippet.

Common Task Workflows

Workflow 1: Create a New Dev Container from Scratch

  1. Load references/core-concepts.md for the full property reference
  2. Choose orchestration method: image (simplest), build.dockerfile, or dockerComposeFile
  3. Add features for tools (Node.js, Python, Git, Docker CLI, etc.)
  4. Set remoteUser to a non-root user for security
  5. Add customizations.vscode.extensions and settings for IDE consistency
  6. Add postCreateCommand to install dependencies automatically
  7. Add forwardPorts for any app ports
{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
      "settings": { "editor.formatOnSave": true }
    }
  },
  "postCreateCommand": "npm install",
  "forwardPorts": [3000],
  "remoteUser": "node"
}

Workflow 2: Add a Tool via Features

  1. Load references/features-templates.md
  2. Browse the official registry or GitHub Container Registry
  3. Add the feature with a pinned version to devcontainer.json
  4. Use overrideFeatureInstallOrder if ordering matters

Workflow 3: Multi-Container Setup with Docker Compose

  1. Load references/advanced-config.md
  2. Create docker-compose.yml for services (app, database, cache)
  3. Create docker-compose.dev.yml for development overrides (source mounts, debug ports)
  4. Set dockerComposeFile to both files in devcontainer.json
  5. Set service to the container the IDE should attach to
  6. Set shutdownAction: "none" to keep services running when IDE closes

Workflow 4: Speed Up Dev Container Builds

  1. Load references/performance-security.md
  2. Order Dockerfile instructions from least-changed to most-changed
  3. Use RUN --mount=type=cache for package managers
  4. Use named volumes for node_modules / heavy dependency directories
  5. Pre-build and push image in CI; reference the pre-built image in devcontainer.json

Workflow 5: Troubleshoot a Permission or Credential Issue

  1. Load references/troubleshooting.md
  2. For UID mismatch: ensure updateRemoteUserUID: true (default on Linux)
  3. For SSH: ensure local SSH agent is running; the extension auto-forwards it
  4. For Git inside container: use SSH agent forwarding; do not copy private keys

Resource Summaries

| File | Contents | Lines | |------|----------|-------| | references/core-concepts.md | Full devcontainer.json property reference, lifecycle hooks, location precedence | ~280 | | references/features-templates.md | Consuming and authoring Features, Templates distribution, version pinning | ~260 | | references/advanced-config.md | Multi-container, Docker-in-Docker/from-Docker, Kubernetes, Codespaces, DevPod | ~280 | | references/performance-security.md | Layer caching, named volumes, pre-built images, non-root users, secrets | ~270 | | references/troubleshooting.md | Permission errors, slow I/O, SSH/GPG credentials, lifecycle script issues | ~200 |

Best Practices

  • Version-pin everything — pin Features (feature:1) and base images (python:3.12) for reproducibility
  • Non-root by default — always set remoteUser to a non-root user; use updateRemoteUserUID: true on Linux
  • Automate setup — use postCreateCommand to install dependencies so the environment is immediately usable
  • Don't modify production Compose — use a docker-compose.dev.yml override for dev-specific additions
  • Pre-build images in CI — reduces startup from minutes to seconds; embed metadata in image labels
  • Never bake secrets into images — use SSH agent forwarding, BuildKit secret mounts, or .env files (git-ignored)
  • Named volumes for heavy directories — on macOS/Windows, mount node_modules etc. into named volumes for native I/O speed

External References