init-pixi-project
Initialize and scaffold a new Pixi-managed Python project, or upgrade an existing one. Use when the user explicitly mentions "init", "initialize", or "setup" in conjunction with "pixi". Handles existing projects by prompting for confirmation before merging.
Best use case
init-pixi-project is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Initialize and scaffold a new Pixi-managed Python project, or upgrade an existing one. Use when the user explicitly mentions "init", "initialize", or "setup" in conjunction with "pixi". Handles existing projects by prompting for confirmation before merging.
Teams using init-pixi-project should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/init-pixi-project/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How init-pixi-project Compares
| Feature / Agent | init-pixi-project | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Initialize and scaffold a new Pixi-managed Python project, or upgrade an existing one. Use when the user explicitly mentions "init", "initialize", or "setup" in conjunction with "pixi". Handles existing projects by prompting for confirmation before merging.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Initialize Pixi Project
## References
- **Usage & Commands**: See [references/pixi-usage.md](references/pixi-usage.md) for details on `pixi search`, `add`, and `run`.
## Workflow
### 1. Safety Check & Parameters
1. **Check for Existing Artifacts**: Look for `pixi.lock`, `pixi.toml`, or a `pyproject.toml` containing `[tool.pixi]`.
2. **Prompt if Exists**: If any of these exist, **PAUSE and ASK** the user:
> "Existing Pixi configuration detected. Proceeding will scaffold the directory structure and attempt to merge standard dependencies (scipy, ruff, etc.) into the current environment. This might affect existing functionality. Do you want to proceed?"
3. **Abort if Rejected**: If the user declines, stop.
4. **Determine Parameters** (if proceeding):
- **Format**: Default to `pyproject` unless user specifies otherwise.
- **Python Version**: Target one minor version behind latest stable (e.g., 3.12).
### 2. Initialization (Merge/Create)
Attempt to initialize Pixi.
- **Run**: `pixi init [PATH] --format [pyproject|pixi] -c conda-forge`
- **Handle Existing**:
- If the command fails because the project is already initialized, verify that `[tool.pixi]` exists in the manifest.
- If it exists, skip to the next step.
- If `pyproject.toml` exists but lacks Pixi config, the agent should try to append the default Pixi configuration or ask the user if `pixi init` didn't do it automatically.
### 3. Post-Initialization Configuration
#### A. Handle Custom Project Name
If the user specified a project name different from the current directory name:
1. **Rename Source**: `mv src/<dir_name> src/<project_name>`
2. **Update Manifest**: Edit `pyproject.toml` to replace the old name with the new one in:
- `[project] name = "..."`
- `[tool.pixi.pypi-dependencies]` section (rename the key).
#### B. Scaffolding (Idempotent)
Run the scaffolding script. Pass the project name if custom.
```bash
python <path_to_skill>/scripts/scaffold_structure.py [PATH] --package-name <project_name>
```
#### C. Gitignore
Check `.gitignore`. Append the following if not present:
```gitignore
.pixi/
tmp/
.git/
```
#### D. Install Python and Dependencies (Smart Merge)
1. **Check Python**: Check if `python` is already a dependency.
- If yes, respect the existing version (or ask user if they want to override).
- If no, add it: `pixi add python=<version>`
2. **Add Standard Packages**:
- Attempt to add the standard stack:
```bash
pixi add --pypi scipy mdutils ruff mkdocs-material mypy attrs omegaconf imageio
```
- **Conflict Handling**: If `pixi add` fails due to conflicts with existing packages, try to resolve by:
- Installing the non-conflicting subset.
- Reporting specific conflicts to the user and asking for guidance.
3. **Finalize**: Run `pixi install`.
### 4. Verification
- Verify the environment is usable (`pixi shell` works).
- Verify directory structure.Related Skills
pixi-make-offline-channel
Use when the user wants to create a self-hosted, offline-installable Conda channel (mirror) containing a specific subset of packages using Pixi.
pixi-make-cu-build-env
Guides the agent to setup a new or existing Pixi environment for compiling C++ and CUDA code. It ensures the correct compilers, toolkits, and CMake configurations are in place for a robust user-space build.
pixi-install-nvidia
Use when the user says "use pixi to install <some nvidia tool>" (or similar) and wants NVIDIA/CUDA/GPU packages installed via Pixi (no sudo/apt), e.g., CUDA toolkit pieces, cuDNN/NCCL, PyTorch CUDA builds, RAPIDS.
init-config-devbox
Performs initial configuration of a development host with a fixed sequence: setup proxy first, then configure pixi/uv/npm/bun global tooling, and finally configure Claude Code. Use only when explicitly invoked by name for first-time host bootstrap or full re-bootstrap.
docker-pixi-project-offline
Scripted process to build and verify a Pixi-managed project in Docker, then produce a portable WORKDIR/product directory for air-gapped use.
pei-docker-usage
Helper for PeiDocker (`pei-docker-cli`). Trigger ONLY when the user explicitly requests PeiDocker usage OR when working within a PeiDocker-generated project (indicated by `user_config.yml`).
conan-basic-usage
Basic operations for the Conan C++ package manager. Use when the user explicitly asks to 'use conan' for tasks like creating projects, installing dependencies, or building packages, or asks for 'how to' guidance on Conan setup.
explore-dnn-model
Manual invocation only; use only when the user explicitly requests `explore-dnn-model` by name. Explore how to run a given DNN model checkpoint in the current Python environment by locating weights + upstream source code, resolving dependencies with user confirmation, running reproducible experiments under `tmp/`, and producing reports about I/O contracts, timing, and profiling.
openspec-ext-revise-by-decision
Manual invocation only; use only when the user explicitly requests `openspec-ext-revise-by-decision` by exact name. Revise OpenSpec change artifacts from a review or decision document that contains questions plus `DECISION` blocks, applying chosen decisions from a review file such as `openspec/changes/<change>/review/review-*.md` back into proposal, design, specs, and tasks.
openspec-ext-review-plan
Review an OpenSpec change (or a single OpenSpec change artifact file) for completeness, coherence, and alignment with existing system design; capture actionable feedback plus open questions; write a review report under the change directory (review/review-YYYYMMDD-HHMMSS.md).
openspec-ext-respond-to-review
Read an OpenSpec review report critically, evaluate the reviewer's proposals and findings against the current change artifacts and repository context, and write developer-owned final decisions/responses back into the review document. Use when the user explicitly mentions `openspec` or points to a path under `openspec/` while asking to examine a review report carefully, decide open questions, respond to findings, fill `DECISION` blocks, respond to an OpenSpec review file, or record final answers in an OpenSpec review document without yet revising the proposal, design, specs, or tasks.
openspec-ext-hack-through-test
Manual invocation only. OpenSpec-specific hack-through-testing workflow targeting production-level end-to-end paths using real data and real user workflows — not CI smoke/unit/integration tests. Three subskills: `propose` to create an OpenSpec change with HTT-ready test cases (automatic scripts and interactive guides) by invoking `openspec-propose` or `openspec-ff-change`, `revise` to update an existing OpenSpec change so its artifacts support hack-through-testing-driven implementation and testing, and `run` to exercise an implemented OpenSpec change through the full hack-through-testing loop (in-place by default, or in a disposable snapshot worktree when requested). Use when the user explicitly asks for `openspec-ext-hack-through-test`, points to `openspec/changes/...` while asking to propose, revise, run, exercise, or prepare work under hack-through-testing principles, or wants OpenSpec work shaped for fast blocker discovery through patch-forward testing.