/devcontainer-setup

name: devcontainer-setup
description: 'Use when adding a devcontainer or isolated dev environment to a repo that lacks one, for Python, Node/TypeScript, Rust, Go, or a combination. Not for editing an existing devcontainer.'
disable-model-invocation: true

Devcontainer setup

Contract

| Field | Bound contract | |---|---| | Trigger | The user asks to add a new devcontainer or isolated Claude Code development environment to a repository that does not already have one, for Python, Node/TypeScript, Rust, Go, or a supported combination. | | Authority | Reversible local: writes only the repository's `.devcontainer/` directory; rollback is version control. No remote mutation. No container is built, launched, published, or pushed. | | Side effect | Creates or replaces the five generated files under `.devcontainer` (Dockerfile, devcontainer.json, post_install.py, .zshrc, and install.sh) with project substitutions and merged language-specific features, settings, extensions, commands, and persistent-volume declarations. | | Done | All template placeholders are resolved; devcontainer.json is valid; every detected language is represented without duplicate configuration; postCreateCommand composes all required setup commands; the security mounts and token-forwarding contract are explicit; and the user receives both VS Code and CLI startup instructions without claiming the container was built or launched unless it was. |

Inputs

Required: the repository root to scan for language manifests and to write `.devcontainer/`.

Optional, supplied by the user when known: a human-readable project name (otherwise inferred), a preferred Python version (otherwise the default from the base template), and a package manager choice for Node/TypeScript (otherwise detected from the lockfile).

Procedure

1. **Reject modification requests.** If `.devcontainer/` already exists, stop: this skill only adds a new devcontainer. Direct the user to edit the existing configuration. Do not trigger for general Docker, production container, or container lifecycle questions. **Done when:** the skill confirms `.devcontainer/` is absent, or stops and directs the user to edit the existing config.

2. **Infer project name and slug.** Probe in order and use the first match: `package.json` `name` field, `pyproject.toml` `project.name`, `Cargo.toml` `package.name`, `go.mod` module path (last segment after `/`), then the repository directory name as fallback. Derive the slug by lowercasing and replacing spaces and the underscore with hyphens. Keep the human-readable name distinct from the slug. **Done when:** a human-readable name and a derived slug are recorded.

3. **Detect the language stack.** Detect each language from its manifest: Python from `pyproject.toml`, `requirements.txt`, `setup.py`, or `*.py`; Node/TypeScript from `package.json` or `tsconfig.json`; Rust from `Cargo.toml`; Go from `go.mod` or `go.sum`. Record every detected language; multi-language projects configure all of them. **Done when:** every detected language is recorded, or the skill stops because none was detected.

4. **Generate the five files from the base templates.** Substitute `{{PROJECT_NAME}}` with the human-readable name and `{{PROJECT_SLUG}}` with the slug in Dockerfile, devcontainer.json, post_install.py, .zshrc, and install.sh. The base template carries Claude Code with marketplace plugins, sandboxing via bubblewrap and socat, Python via uv, Node via fnm, ast-grep, network isolation tools, security mounts (`.devcontainer/` mounted read-only to prevent container escape), token forwarding of `CLAUDE_CODE_OAUTH_TOKEN` and `ANTHROPIC_API_KEY` via `remoteEnv`, and modern CLI tools. **Done when:** all five files are written with the two placeholders substituted.

5. **Re-ground pinned toolchain versions and review broad privileges.** Do not copy pinned toolchain versions or broad container privileges (NET_ADMIN capability, iptables/ipset, bubblewrap sandboxing) verbatim from the source template. Confirm each pinned version against the current upstream release the project targets, and confirm each broad privilege is justified for this project's isolation needs; narrow or drop privileges that are not justified. Record the chosen versions and privilege set in the generated files. **Done when:** every pinned version is re-grounded and every broad privilege is justified or dropped, with the choice recorded.

6. **Merge language-specific configuration in priority order.** For each detected language, merge its devcontainer features, VS Code extensions, VS Code settings, and postCreateCommand segment into devcontainer.json and the Dockerfile. Priority order when multiple languages are present: Python (primary, uses the Dockerfile for uv and Python installation), Node/TypeScript (uses a devcontainer feature), Rust (uses a devcontainer feature), Go (uses a devcontainer feature). Merge extensions and settings from all detected languages; do not duplicate entries.

• Python: if `pyproject.toml` declares a Python version different from the base default, set it in the Dockerfile via `uv python install <version> --default`. Add extensions `ms-python.python`, `ms-python.vscode-pylance`, `charliermarsh.ruff`. Add settings `python.defaultInterpreterPath` to `.venv/bin/python` and a `[python]` formatter block using ruff with organize-imports on save. postCreateCommand segment: `rm -rf .venv && uv sync && uv run /opt/post_install.py` when `pyproject.toml` exists.
• Node/TypeScript: no Dockerfile additions. Add the `biomejs.biome` extension. Set `biomejs.biome` as the default formatter and enable its safe source fixes on save; do not introduce ESLint or Prettier. Detect the package manager from the lockfile: `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`, `yarn.lock` → `yarn install --immutable`, `package-lock.json` → `npm ci`, no lockfile → initialize pnpm 11 and run `pnpm install`. postCreateCommand segment chains the chosen install after the base co