Enforce Python tooling conventions for uv, ty, Ruff, pytest, and pyproject.toml. Use when working on .py files or Python project config. NOT for JS/TS, shell scripts, CI design, profiling, or test architecture.
Enforce Python tooling conventions for uv, ty, Ruff, pytest, and pyproject.toml. Use when working on .py files or Python project config. NOT for JS/TS, shell scripts, CI design, profiling, or test architecture.
This skill enforces a consistent Python tooling stack across the project: uv for package and environment operations, ty for type checks, ruff for linting and formatting, and pytest for tests. It keeps detailed library, testing, performance, and exception guidance behind reference files so the active skill stays lightweight.
Activates automatically when working on Python files. Applies the hard tooling contract and loads detailed references only when needed.
/python-conventions
Displays a summary of all active conventions without applying changes.
/python-conventions check
Verifies the tooling contract only — checks command execution through uv, dependency management via pyproject.toml, ty typing, ruff linting/formatting, and pytest test entrypoints without applying broader refactors.
When starting new Python work and no stronger local constraint exists, use references/library-preferences.md for guided defaults. These choices are preferences, not mandatory rewrites:
Use references/performance-tips.md for quick Python profiling and optimization patterns. Route broad profiling, regression analysis, or benchmark interpretation to performance-profiler.
Use references/testing-patterns.md for fixtures, markers, tmp_path, monkeypatch, parametrization, and coverage policy. Route suite strategy, fixture architecture, and cross-language test plans to test-architect.
javascript-conventionsJS/TS tooling conventions. Enforce pnpm. Use when working on JS/TS files or package.json. NOT for Python, backend-only, or shell scripts.
1. Apply this skill only when Python files, Python tooling, or `pyproject.toml` are the primary surface of the task.
2. Read `references/redirection-boundaries.md` when Python appears alongside shell, JS/TS, or other dominant workstreams.
3. Enforce the hard requirements in `references/tooling-contract.md` for package management, command execution, linting, type checking, and tests.
4. Check `references/exceptions.md` before recommending any legacy or constrained-environment deviation.
5. Read `references/library-preferences.md` only when choosing libraries for new Python work.
### Empty / Help
1. Summarize the hard requirements: `uv`, `uv run`, `uv add`, `ty`, `ruff`, `pytest`, and `pyproject.toml`.
2. Show the difference between hard requirements and guided preferences.
3. Point to the exact reference files for tooling, exceptions, libraries, testing, performance, and mixed-language routing.
### `check`
1. Verify tooling compliance only; do not widen into full implementation advice unless the user asks.
2. Report whether the project uses `uv`, `uv run`, `ty`, `ruff`, `pytest`, and `pyproject.toml` in the expected ways.
3. Flag legacy or exception-path deviations and require the reason to match `references/exceptions.md`.
4. Reject recommendations that replace repo-required tooling with `mypy`, `pip install`, or bare `python`.
## Hard Requirements
- **Package manager**: use `uv` for all Python package operations
- **Dependencies**: use `uv add`, `uv add --group dev`, `uv remove`, and `uv lock --upgrade-package <pkg>` as appropriate
- **Reproducible installs**: use `uv sync --locked` when validating an existing lockfile workflow
- **Project config**: keep Python project configuration in `pyproject.toml`
- **Type checking**: use `uv run ty check`, not `mypy`
- **Linting**: use `uv run ruff check` and `uv run ruff format`
- **Testing**: use `uv run pytest`
- **Task running**: use `uv run <command>` for Python command execution
### Virtual Environments
- Let `uv` manage virtual environments automatically
- Never manually create or activate `.venv` directories
- Use `uv run` to execute within the project environment
## Guided Preferences
Guided library preferences apply only when starting new Python work and no stronger local constraint already exists. Read `references/library-preferences.md` before recommending replacements for an established stack.
## Project Structure
- Use `pyproject.toml` for all project metadata and dependencies
- Place source code in a package directory matching the project name
- Use `uv` workspace members for monorepo sub-packages
- Run the required lint, format, type-check, and test sequence from `references/tooling-contract.md` before considering Python work complete
## Performance Conventions
1. Profile before optimizing.
2. Use `references/performance-tips.md` for quick Python profiling and optimization patterns.
3. Route broad profiling, regression analysis, or performance investigation to `performance-profiler`.
## Testing Conventions
1. Use pytest for Python tests and configure project test defaults in `pyproject.toml`.
2. Use `references/testing-patterns.md` for fixtures, markers, `tmp_path`, `monkeypatch`, parametrization, and coverage policy.
3. Route test strategy, suite design, fixture architecture, or cross-language test plans to `test-architect`.
## Validation Contract
Before declaring changes to this skill complete, run:
1. `uv run wagents validate`
2. `uv run wagents eval validate`
3. `uv run python path/to/audit.py skills/python-conventions/ --format json`
4. `uv run wagents package python-conventions --dry-run`
5. `git diff --check`
After changing skill definitions, public descriptions, reference files, or eval behavior, invoke `docs-steward` if available and then run `uv run wagents readme --check`.
## Critical Rules
1. Reject Python setup advice that uses `pip install`, `uv pip install`, or bare `python` when the task is not explicitly on an approved exception path.
2. Require `uv add` for runtime dependencies and `uv add --group dev` for development-only dependencies unless `references/exceptions.md` justifies a legacy or constrained-environment deviation.
3. Require `uv run ty check` for type checking; do not recommend `mypy` or bare `ty check` as the default path in this repo.
4. Treat `uv run ruff check`, `uv run ruff format`, `uv run ty check`, and `uv run pytest` as the default completion gate for Python changes unless an exception is documented.
5. Do not edit `uv.lock` by hand; use `uv lock`, `uv sync`, or dependency commands.
6. Do not present guided library preferences as mandatory replacements for an already-established local stack.
7. Read `references/exceptions.md` before approving a legacy toolchain, alternate environment manager, or alternate library path.
8. Redirect mixed-language or non-Python-primary work through `references/redirection-boundaries.md` instead of force-fitting this skill onto the whole task.
**Canonical terms** (use these exactly):
- `uv` -- the required package manager and task runner
- `ty` -- the required type checker (not mypy)
- `uv run ty check` -- the required type-check command
- `ruff` -- the required linter and formatter
- `pyproject.toml` -- the single source of project configuration
- `uv run` -- prefix for all Python command execution
- Incidental Python file in a broader non-Python task: enforce only the hard requirements that touch the Python-owned surface, then route mixed-workflow questions through `references/redirection-boundaries.md`.
- Python-primary feature or refactor work: apply the full operator contract, including tooling, testing, and guided preferences where relevant.
- Repo-wide Python tooling or migration work: use `check`, `references/tooling-contract.md`, and `references/exceptions.md` to separate hard violations from documented transition paths.
## Progressive Disclosure
- Do not load every reference by default.
- Read `references/tooling-contract.md` first for command-sequence questions.
- Read `references/redirection-boundaries.md` when shell, JS/TS, CI, or framework-specific work is mixed into the request.
- Read `references/exceptions.md` only when the task appears to require legacy, corporate, or constrained-environment exceptions.
- Read `references/library-preferences.md` only when selecting libraries for new Python work.
- Read performance or testing references only when the active task actually touches those areas.
