| name | attach-ubuntu |
| description | Launch or reuse an Ubuntu Docker container for the current project, bind-mount it at /workdir, preconfigure VS Code attached-container defaults, and best-effort open the project in a new VS Code Dev Containers window. Use when users want a disposable Ubuntu test environment on macOS with Docker Desktop and the Dev Containers extension. |
Attach Ubuntu
Use this skill when the user wants a quick Ubuntu test container for the current
project without adding a repo-local .devcontainer/ as the primary path.
Workflow
- Use
scripts/attach-ubuntu.sh from the target project directory when
script execution is permitted by the current user and repository policy.
- Keep one container per project folder by deriving the container name from the
current directory unless the user explicitly overrides it.
- For a standalone project, bind-mount the current host directory to
/workdir and set the container working directory to /workdir.
- When the current project folder lives inside a larger Git repository and
does not contain its own valid
.git, bind-mount the repo root at
/opt/attach-ubuntu/repo-root instead, then expose the requested project
subdirectory through a /workdir symlink inside the container so
version-aware tools like setuptools-scm still see the real repository.
- Merge a VS Code attached-container config for the derived container name so
manual fallback opens
/workdir and keeps the openai.chatgpt extension
present without colliding with other ubuntu:24.04 attach sessions.
- Bootstrap the container toolchain after startup:
- install base Ubuntu build tools such as
make, build-essential, git,
curl, and Python tooling
- detect a preferred Python version from
.python-version, runtime.txt,
or pyproject.toml requires-python when possible
- if
pyproject.toml exists, prefer the project's own make env or
make install target with a container-only virtual environment at
/opt/attach-ubuntu/venv; otherwise fall back to creating that venv and
installing the project in editable mode
- Best-effort open a new VS Code window with the
attached-container remote
URI. If that attach request fails on the user’s installation, fall back to:
Dev Containers: Attach to Running Container...
Notes
- The supported VS Code attach entrypoint remains the Command Palette or Remote
Explorer. The script still uses the internal
attached-container URI as an
automation shortcut because it works on current VS Code builds, but keep the
manual fallback in the output.
- VS Code defaults to image-level attached-container config, but the script
writes a container-name config directly because it is more stable when
multiple
ubuntu:24.04 attach windows are active at the same time.
- The script auto-activates
/opt/attach-ubuntu/venv in interactive Bash
terminals when that virtual environment exists, and it exports
VENV=/opt/attach-ubuntu/venv so later make all runs use the container
venv instead of a host-created .venv.
- The script is idempotent. It reuses the existing container when the image,
mount source, and working directory already match; otherwise it recreates it.
- Optional cleanup is built in via
--stop and --remove, and bootstrap can
be skipped with --no-bootstrap.
Execution Mode
Scripts in this skill are reference-only by default. Execute
scripts/attach-ubuntu.sh only when the user explicitly starts the request
with Run or Execute (or equivalent). If execution is not clearly requested,
explain the relevant command instead of running it.
Commands
- Launch or reuse the container and request a VS Code attach:
./attach-ubuntu/scripts/attach-ubuntu.sh
- Prepare the container only:
./attach-ubuntu/scripts/attach-ubuntu.sh --no-open
- Prepare the container but skip toolchain and dependency installation:
./attach-ubuntu/scripts/attach-ubuntu.sh --no-open --no-bootstrap
- Stop the per-project container:
./attach-ubuntu/scripts/attach-ubuntu.sh --stop
- Remove the per-project container:
./attach-ubuntu/scripts/attach-ubuntu.sh --remove
Learning Loop
When using this skill, capture durable, reusable, public-safe learnings back
into this skill's local source materials before completion when the current task
contract allows source edits. Update the narrowest appropriate surface:
SKILL.md for runtime rules, references/ for detailed guidance, assets/
for reusable templates, scripts/ for deterministic helpers, and README or
changelog entries for human-facing or release-note updates.
If the current task is explicitly read-only/report-only, or source writes are
outside this skill's task contract, do not edit skill sources; report the
skipped source update instead.
Do not capture secrets, private URLs, customer data, raw logs, one-off local
state, or unverified/vendor-specific claims. If a useful learning is not safe,
not evidence-backed, or outside this skill's scope, report that it was skipped.
