dotfiles/.config/opencode/skills/python-development/SKILL.md

name, description, permalink

name	description	permalink
python-development	Python ecosystem defaults and workflows using uv for packaging and ruff for linting/formatting	opencode-config/skills/python-development/skill

Python Development

Load this skill when a repo or lane involves Python code (presence of pyproject.toml, setup.py, requirements*.txt, or .py files as primary source).

Defaults

Concern	Tool	Notes
Package/venv management	uv	Replaces pip, pip-tools, and virtualenv
Linting + formatting	ruff	Replaces flake8, isort, black
Test runner	pytest	Unless repo already uses another runner
Type checking	pyright or mypy	Use whichever the repo already configures

Core Workflow

1. Bootstrap — uv sync (or uv pip install -e ".[dev]") to create/refresh the venv.
2. Lint — ruff check . then ruff format --check . before committing.
3. Test — pytest with the repo's existing config. Follow TDD default policy.
4. Add dependencies — uv add <pkg> (runtime) or uv add --dev <pkg> (dev). Do not edit pyproject.toml dependency arrays by hand.
5. Lock — uv lock after dependency changes.

Conventions

• Prefer pyproject.toml over setup.py/setup.cfg for new projects.
• Keep ruff config in pyproject.toml under [tool.ruff].
• Use uv run <cmd> to execute tools inside the managed venv without activating it.
• Pin Python version via .python-version or pyproject.toml requires-python.

Docker Integration

When the repo runs Python inside Docker, install dependencies with uv pip install inside the container. Mount a named volume for the uv cache to speed up rebuilds.

Red Flags

• Using pip install directly instead of uv.
• Running black or isort when ruff is configured.
• Missing uv.lock after dependency changes.
• Editing dependency arrays in pyproject.toml by hand instead of using uv add.