Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add trailofbits/skills --skill modern-python -a cursor -y
Download plugins/modern-python/skills/modern-python/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does modern-python live?
The publisher keeps it at https://github.com/trailofbits/skills.
Which agents can use modern-python?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
name: modern-python
description: Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
Always use uv add and uv remove to manage dependencies
Never manually activate or manage virtual environments—use uv run for all commands
Use [dependency-groups] for dev/test/docs dependencies, not [project.optional-dependencies]
Decision Tree
What are you doing?
│
├─ Single-file script with dependencies?
│ └─ Use PEP 723 inline metadata (./references/pep723-scripts.md)
│
├─ New multi-file project (not distributed)?
│ └─ Minimal uv setup (see Quick Start below)
│
├─ New reusable package/library?
│ └─ Full project setup (see Full Setup below)
│
└─ Migrating existing project?
└─ See Migration Guide below
For simple multi-file projects not intended for distribution:
# Create project with uv
uv init myproject
cd myproject
# Add dependencies
uv add requests rich
# Add dev dependencies
uv add --group dev pytest ruff ty
# Run code
uv run python src/myproject/main.py
# Run tools
uv run pytest
uv run ruff check .
Full Project Setup
If starting from scratch, ask the user if they prefer to use the Trail of Bits cookiecutter template to bootstrap a complete project with already preconfigured tooling.
See pyproject.md for complete configuration reference.
Key sections:
[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []
[dependency-groups]
dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
lint = ["ruff", "ty"]
test = ["pytest", "pytest-cov"]
audit = ["pip-audit"]
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "COM812", "ISC001"]
[tool.pytest]
addopts = ["--cov=myproject", "--cov-fail-under=80"]
[tool.ty.terminal]
error-on-warning = true
[tool.ty.environment]
python-version = "3.11"
[tool.ty.rules]
# Strict from day 1 for new projects
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"
3. Install Dependencies
# Install all dependency groups
uv sync --all-groups
# Or install specific groups
uv sync --group dev
4. Add Makefile
.PHONY: dev lint format test build
dev:
uv sync --all-groups
lint:
uv run ruff format --check && uv run ruff check && uv run ty check src/
format:
uv run ruff format .
test:
uv run pytest
build:
uv build
Migration Guide
When a user requests migration from legacy tooling:
From requirements.txt + pip
First, determine the nature of the code:
For standalone scripts: Convert to PEP 723 inline metadata (see pep723-scripts.md)
For projects:
# Initialize uv in existing project
uv init --bare
# Add dependencies using uv (not by editing pyproject.toml)
uv add requests rich # add each package
# Or import from requirements.txt (review each package before adding)
# Note: Complex version specifiers may need manual handling
grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
uv add "$pkg" || echo "Failed to add: $pkg"
done
uv sync
Then:
Delete requirements.txt, requirements-dev.txt
Delete virtual environment (venv/, .venv/)
Add uv.lock to version control
From setup.py / setup.cfg
Run uv init --bare to create pyproject.toml
Use uv add to add each dependency from install_requires
Use uv add --group dev for dev dependencies
Copy non-dependency metadata (name, version, description, etc.) to [project]
Delete mypy.ini, pyrightconfig.json, or [tool.mypy]/[tool.pyright] sections
Add ty: uv add --group dev ty
Run uv run ty check src/
Quick Reference: uv Commands
Command
Description
uv init
Create new project
uv init --package
Create distributable package
uv add <pkg>
Add dependency
uv add --group dev <pkg>
Add to dependency group
uv remove <pkg>
Remove dependency
uv sync
Install dependencies
uv sync --all-groups
Install all dependency groups
uv run <cmd>
Run command in venv
uv run --with <pkg> <cmd>
Run with temporary dependency
uv build
Build package
uv publish
Publish to PyPI
Ad-hoc Dependencies with --with
Use uv run --with for one-off commands that need packages not in your project:
# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"
# Run a module with temporary deps
uv run --with rich python -m rich.progress
# Multiple packages
uv run --with requests --with rich python script.py
# Combine with project deps (adds to existing venv)
uv run --with httpx pytest # project deps + httpx
When to use --with vs uv add:
uv add: Package is a project dependency (goes in pyproject.toml/uv.lock)
--with: One-off usage, testing, or scripts outside a project context
Download plugins/modern-python/skills/modern-python/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does modern-python live?
The publisher keeps it at https://github.com/trailofbits/skills.
Which agents can use modern-python?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.