devcontainers

Files (24)

• SKILL.md
• cli.md · references/
• devcontainer-json.md · references/
• distribution.md · references/
• features.md · references/
• README.md · references/generated/
• feature-authoring-best-practices.md · references/generated/
• feature-authoring-guide.md · references/generated/
• features-distribution.md · references/generated/
• features-index.md · references/generated/
• features-spec.md · references/generated/
• json-reference.md · references/generated/
• manifest.json · references/generated/
• templates-distribution.md · references/generated/
• templates-index.md · references/generated/
• templates-spec.md · references/generated/
• vscode-cli.md · references/generated/
• vscode-containers.md · references/generated/
• vscode-create.md · references/generated/
• vscode-tips.md · references/generated/
• gotchas.md · references/
• joe-devcontainer.md · references/
• templates.md · references/
• update.js · scripts/

SKILL.md (first lines)

# Dev Containers

Core principle: A devcontainer is a version-controlled, reproducible development environment. Prefer features over Dockerfile layers for common tools; write Dockerfiles only for custom tooling not available as a feature.

## Route First

| Task | Reference |
|---|---|
| Create or edit devcontainer.json | `references/devcontainer-json.md` |
| Add or find features | `references/features.md` + `references/generated/features-index.md` |
| Author a custom feature | `references/features.md` (authoring section) |
| Create or publish a template | `references/templates.md` |
| devcontainer CLI commands | `references/cli.md` |
| Publish features/templates to OCI/GHCR | `references/distribution.md` |
| Debug startup, mounts, GPU, PATH, permissions | `references/gotchas.md` |
| Joe's personal devcontainer (ghcr.io/joeblackwaslike/devcontainer) | `references/joe-devcontainer.md` |
| Browse all available features / templates | `references/generated/features-index.md` or `references/generated/templates-index.md` |

Read the most specific reference first; read others only if the first doesn't cover the need.

## Quick Patterns

### Minimal devcontainer.json

```json
{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "lts" }
  }
}
```

### Config file discovery order

1. `.devcontainer/devcontainer.json`
2. `.devcontainer.json` (project root)
3. `.devcontainer/<subfolder>/devcontainer.json` (multi-config; user selects at open time)

### `image` vs `build`

Use `image` when the base needs no customization.
Use `build.dockerfile` when you need custom layers (apt installs, baked files, config not available as a feature).

```json
{ "build": { "dockerfile": "Dockerfile", "context": "..", "args": { "NODE_VER": "18" } } }
```

### Lifecycle execution order

```
initializeCommand   (host machine, before anything)
→ image pull / build
→ features install  (as root)
→ onCreateCommand   (container, once on creation)
→ postCreateCommand (container, once; runs as remoteUser)
→ postStartCommand  (container, every start/rebuild)
→ postAttachCommand (container, every editor attach)
```

Any non-zero exit skips all subsequent scripts. Scripts can be a string, array, or parallel object:

```json
"postCreateCommand": {
  "deps": "npm install",
  "types": "npm run typecheck"
}
```

### Environment variables: `containerEnv` vs `remoteEnv`

| Property | Set at | Visible to |
|---|---|---|
| `containerEnv` | Image build time | All processes in container |
| `remoteEnv` | Runtime (by tooling) | VS Code terminals, tasks, debug only |

Always append to PATH — never overwrite:

```json
"remoteEnv": { "PATH": "${containerEnv:PATH}:/my/custom/bin" }
```

### VS Code customizations

```json
"customizations": {
  "vscode": {
    "extensions": ["ms-python.python", "esbenp.prettier-vscode"],
    "settings": { "editor.formatOnSave": true }
  }
}
```

## Red Flags — Stop

- Installing a common tool in `postCreateCommand` when a Feature exists for it
- Setting `PATH` in `remoteEnv` without `${containerEnv:PATH}:` prefix
- Adding `"--gpus all"` to `runArgs` without guarding for non-GPU hosts
- Publishing to GHCR without setting package visibility to **public**
- Editing devcontainer.json and expecting auto-rebuild — VS Code requires explicit `Dev Containers: Rebuild Container`
- Running `postCreateCommand` as root when the intent is user-level setup (use `remoteUser`)

## Completion Criteria

- Config validates: `devcontainer read-configuration --workspace-folder .` exits 0
- Container starts: `devcontainer up --workspace-folder .` exits 0
- All lifecycle scripts exit 0
- For features: `devcontainer features test -f ./src/<feature>` passes
- For distribution: GHCR package is set to **public** and version is confirmed in registry

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills