playbooks

home / skills / benchflow-ai / skillsbench / setup-env

setup-env skill

/tasks/setup-fuzzing-py/environment/skills/setup-env

This skill sets up Python project environments using uv, installing dependencies and running scripts for pyproject.toml or requirements.txt projects.

npx playbooks add skill benchflow-ai/skillsbench --skill setup-env

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.7 KB
---
name: setup-env
description: "When given a Python project codebase, this skill helps the agent to set up virtual environments, install dependencies, and run scripts."
---

# Skill: Use uv to manage Python environments

## Scope

1. Create a virtual environment
2. Install dependencies
3. Run Python scripts/commands

Assume `uv` is already available on PATH.

---

## Workflow selection

- If `pyproject.toml` exists: use **project workflow** (`uv sync`, `uv run`)
- Else if `requirements.txt` exists: use **pip workflow** (`uv venv`, `uv pip install -r ...`, `.venv/bin/python ...`)
- Else: stop with an error ("No pyproject.toml or requirements.txt found.")

---

## Project workflow (pyproject.toml)

### Create venv + install dependencies

From the repo root (where `pyproject.toml` is):

- `uv sync`

Notes:

- uv maintains a persistent project environment at `.venv` and installs deps there.

### Run scripts / commands (preferred)

Always run within the project environment:

- `uv run -- python <script.py> [args...]`
- `uv run -- python -m <module> [args...]`

Notes:

- `uv run` executes inside the project environment and ensures it is up-to-date.

---

## Pip workflow (requirements.txt)

### Create venv

From the repo root:

- `uv venv` # creates `.venv` by default

### Install dependencies

- `uv pip install -r requirements.txt`

### Run scripts / commands

Run using the venv interpreter directly (no activation required):

- `.venv/bin/python <script.py> [args...]`
- `.venv/bin/python -m <module> [args...]`

(uv will also automatically find and use the default `.venv` in subsequent invocations when you use `uv pip ...` commands.)

---

## Minimal sanity checks (optional)

- `test -x .venv/bin/python`
- `uv pip list` (verify packages installed)

Overview

This skill helps an agent set up Python project environments, install dependencies, and run scripts using the uv tool. It detects project layout and chooses the correct workflow for pyproject.toml or requirements.txt. The goal is to produce a reproducible .venv and run commands inside that environment reliably.

How this skill works

The skill inspects the repository root for pyproject.toml or requirements.txt and selects a workflow. For pyproject.toml it uses uv sync and uv run to manage a persistent project environment at .venv. For requirements.txt it creates a venv with uv venv, installs packages with uv pip install, and runs scripts with the .venv interpreter.

When to use it

  • You need a reproducible virtual environment for a Python project with pyproject.toml.
  • You have a legacy project that lists dependencies in requirements.txt.
  • You must run Python scripts or modules inside the correct project environment.
  • You want consistent, repeatable dependency installation across environments.
  • You need quick verification that a repo can run its example scripts or tests.

Best practices

  • Run from the repository root so uv finds pyproject.toml or requirements.txt reliably.
  • Prefer the project workflow (pyproject.toml) to keep environment state managed by uv sync and uv run.
  • Use uv run -- python -m <module> to execute packages as modules inside the project venv.
  • Verify venv creation with a simple sanity check like test -x .venv/bin/python.
  • Avoid manual activation; call the venv interpreter directly or use uv run to ensure the correct environment.

Example use cases

  • Set up a new contributor environment from a repo that contains pyproject.toml and run the project's demo script.
  • Install dependencies for an older project that only provides requirements.txt and run its test suite with .venv/bin/python -m pytest.
  • Automate CI steps: create the venv, install requirements, and run linters or unit tests inside .venv.
  • Quickly verify that a cloned repository boots by running uv sync or uv pip install then executing example scripts.

FAQ

What if neither pyproject.toml nor requirements.txt exists?

The skill stops with an error: no detectable dependency file. Add one of these files or provide explicit install instructions.

Do I need to activate the virtualenv manually?

No. Prefer uv run -- ... or call .venv/bin/python directly. uv manages and uses .venv automatically for its commands.