Use Pixi Agent Skill

Use Pixi

Use Pixi as the command and environment boundary for this repository.

Inspect before editing

• Run pixi --version, pixi info, and pixi task list when available.
• Locate both pixi.toml and pyproject.toml. Pixi discovers an explicit --manifest-path first, then a local pixi.toml, then a local pyproject.toml, then parent manifests. A sibling pixi.toml therefore wins over pyproject.toml.
• Read the selected manifest, its workspace.platforms, targets, features, environments, tasks, and editable path dependencies.
• Read pixi.lock when reproducibility or CI behavior matters. Do not hand-edit the lockfile.

Choose the dependency owner

• Put Python itself and command-line/system packages supplied by conda-forge under Pixi dependencies.
• Put Python distributions resolved from PyPI under pypi-dependencies or [project.dependencies], according to the repository's existing ownership boundary.
• Represent a local Python project as { path = ".", editable = true } or another relative editable path in Pixi.
• Use target.<platform> for dependencies limited to one supported platform.
• Use a feature when a dependency set is optional and reusable; compose features into named environments.
• Do not use bare pip install inside a Pixi-managed repository. Use pixi add, a manifest edit, and a new lock instead.

Understand the model

• A workspace declares channels and every platform solved into pixi.lock.
• A target narrows configuration to a platform such as linux-64, win-64, or osx-arm64.
• A feature groups optional dependencies, tasks, activation, and targets.
• An environment selects features and produces an installable prefix under .pixi/envs/ by default; named or detached configuration may select another prefix.
• A task is a reproducible command executed inside an environment.
• The lockfile records exact conda and PyPI resolutions for every declared platform.

Make and verify changes

Use the smallest applicable commands:

pixi add PACKAGE
pixi add --pypi PACKAGE
pixi remove PACKAGE
pixi remove --pypi PACKAGE
pixi update PACKAGE
pixi install
pixi run TASK
pixi shell  # interactive use only
pixi task list
pixi lock --check

When adding or removing a dependency, use --feature FEATURE for a named feature and --platform PLATFORM for a platform-specific table. Combine the selectors only when both scopes apply.

For local, intentional manifest changes, run pixi lock, the relevant pixi run task, and pixi lock --check. Inspect the manifest diff and lockfile diff before reporting success.

Keep the lockfile immutable in CI:

pixi install --locked
pixi run --locked TASK

--locked prevents lockfile updates; it does not make environment installation or task execution read-only. Inspect task definitions before running them in any no-write workflow.

CI must not run pixi lock, because that command mutates the lockfile.

IDE boundary

Run pixi install before selecting an interpreter. In AUV, .pixi/envs/default only carries Ruff and ty; select the named environment that owns a package (under .pixi/envs/) as the VS Code python.defaultInterpreterPath folder when analyzing or debugging it. Locate named or detached environments using the prefix reported by pixi info --json, but never commit the returned absolute machine path. Documentation, automation, and terminal commands should use pixi run; Windows and POSIX interpreter paths differ.

Safeguards

• Keep all declared platforms solvable; do not validate only the current host.
• Do not add CUDA or another platform-only dependency to unconditional common dependencies.
• Do not remove or regenerate unrelated environments.
• Do not claim success until the lockfile is current and the requested task passes.

AUV workspace

• Pixi is required only for Python or model work. Do not ask Rust, JavaScript, Protobuf, or documentation contributors to install it.
• The root pixi.toml owns Python tooling; Rust, pnpm, and Buf keep their own toolchains. Never add them to pixi.toml.
• Python package metadata owns runtime dependencies. Edit the package pyproject.toml, then run pixi lock.
• Keep the default environment to Ruff and ty with no python, solvable on linux-64, osx-arm64, and win-64. Do not add a workspace-wide Python pin.
• Give each Python package its own feature that pins python and its dependencies, and compose it into a named environment. Do not share a solve-group between packages that need different Python versions.
• For a package on another Python version, add a directory ruff.toml that extends the root one with its own target-version, and run ty in that package's environment.
• Run pixi run --locked check before handoff when Python files or Pixi metadata change.