Provision Environment

Provisioning a toolchain or runtime

Before you run a build, test, lint, or format command, make sure the tool is actually available, and get there without changing the user's machine. Work through these steps in order and stop at the first that succeeds.

1. Follow declared presets

If the user has declared environment facts (typically an ## Environment block in their ~/.claude/CLAUDE.md, which you receive automatically), follow them: the container runtime to use, the package manager, how toolchains are provided, whether to format in a container, and so on. These win over anything you would infer.

2. Detect what is already there

Probe, do not assume. Check without side effects:

• Binaries: command -v (never run a tool just to see if it errors).
• Container runtime: a present binary is not enough, confirm the daemon: docker info >/dev/null 2>&1, else podman info >/dev/null 2>&1. podman is a drop-in for docker.
• Language package manager: resolve from the lockfile, not from what is installed (pnpm-lock.yaml -> pnpm, package-lock.json -> npm, yarn.lock -> yarn, bun.lockb -> bun).
• Declared project environment: prefer whatever the project ships: manifest.scm, flake.nix, a devcontainer, .tool-versions/.mise.toml, .nvmrc, rust-toolchain.toml.
• OS: uname -s (Linux/Darwin). Assume a POSIX shell; if it is something else, say so and ask.

If the tool the task needs is already on PATH, use it and move on.

3. Provision only non-invasively

If the tool is missing, you may still proceed only by means that leave the host unchanged:

• An ephemeral shell: nix shell ... or guix shell ... (transient, nothing installed into a profile).
• A throwaway container run, for example formatting Rust with no local toolchain:

docker run --rm -v "$PWD":/w -w /w rust: sh -c "rustup component add rustfmt && cargo fmt" (use podman if that is the available runtime).

Never modify the host to satisfy a requirement: no apt/dnf/brew/pacman/apk installs, no global rustup component add on the host, no sudo, no writing to system paths. Provisioning is allowed to be transient, never permanent.

4. Otherwise, ask

If the requirement cannot be met from steps 1-3, do not force it and do not fall back to a host-modifying install. Stop and tell the user exactly what is missing and the options (for example "no Rust toolchain on PATH, and no nix, guix, or container runtime available, how would you like to proceed?"). Let them decide.

Cap the effort

Try the declared/available path, then one non-invasive fallback, then ask. Do not loop retrying the same failing command.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: franzos
• Source: franzos/claude-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.