python-conventions
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.
How do I install this agent skill?
npx skills add https://github.com/wyattowalsh/agents --skill python-conventionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill enforces Python development conventions using tools like uv and Ruff. It includes local validation scripts that execute commands to check project compliance. While it processes project files, it operates within a local context with no identified data exfiltration or remote execution risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
4 files scanned · No issues
What does this agent skill do?
Python Conventions
Apply these conventions when Python work is the primary workstream.
Dispatch
| $ARGUMENTS | Action |
|---|---|
| Active (auto-invoked when Python work is primary) | Apply the operator contract below |
| Empty | Display the convention summary and routing guidance |
check | Verify tooling compliance only |
Reference File Index
| File | Purpose |
|---|---|
references/tooling-contract.md | Required command sequence for install, run, lint, type-check, and test flows |
references/redirection-boundaries.md | When Python conventions should yield to shell, JS/TS, or domain-specific skills |
references/exceptions.md | When to break conventions (legacy, corporate) |
references/library-preferences.md | Guided library defaults for new Python work |
references/performance-tips.md | Profiling tools, optimization patterns quick-reference |
references/testing-patterns.md | Fixture scopes, markers, conftest skeleton |
Operator Contract
Active
- Apply this skill only when Python files, Python tooling, or
pyproject.tomlare the primary surface of the task. - Read
references/redirection-boundaries.mdwhen Python appears alongside shell, JS/TS, or other dominant workstreams. - Enforce the hard requirements in
references/tooling-contract.mdfor package management, command execution, linting, type checking, and tests. - Check
references/exceptions.mdbefore recommending any legacy or constrained-environment deviation. - Read
references/library-preferences.mdonly when choosing libraries for new Python work.
Empty / Help
- Summarize the hard requirements:
uv,uv run,uv add,ty,ruff,pytest, andpyproject.toml. - Show the difference between hard requirements and guided preferences.
- Point to the exact reference files for tooling, exceptions, libraries, testing, performance, and mixed-language routing.
check
- Verify tooling compliance only; do not widen into full implementation advice unless the user asks.
- Report whether the project uses
uv,uv run,ty,ruff,pytest, andpyproject.tomlin the expected ways. - Flag legacy or exception-path deviations and require the reason to match
references/exceptions.md. - Reject recommendations that replace repo-required tooling with
mypy,pip install, or barepython.
Hard Requirements
- Package manager: use
uvfor all Python package operations - Dependencies: use
uv add,uv add --group dev,uv remove, anduv lock --upgrade-package <pkg>as appropriate - Reproducible installs: use
uv sync --lockedwhen validating an existing lockfile workflow - Project config: keep Python project configuration in
pyproject.toml - Type checking: use
uv run ty check, notmypy - Linting: use
uv run ruff checkanduv run ruff format - Testing: use
uv run pytest - Task running: use
uv run <command>for Python command execution
Virtual Environments
- Let
uvmanage virtual environments automatically - Never manually create or activate
.venvdirectories - Use
uv runto 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.tomlfor all project metadata and dependencies - Place source code in a package directory matching the project name
- Use
uvworkspace members for monorepo sub-packages - Run the required lint, format, type-check, and test sequence from
references/tooling-contract.mdbefore considering Python work complete
Performance Conventions
- Profile before optimizing.
- Use
references/performance-tips.mdfor quick Python profiling and optimization patterns. - Route broad profiling, regression analysis, or performance investigation to
performance-profiler.
Testing Conventions
- Use pytest for Python tests and configure project test defaults in
pyproject.toml. - Use
references/testing-patterns.mdfor fixtures, markers,tmp_path,monkeypatch, parametrization, and coverage policy. - Route test strategy, suite design, fixture architecture, or cross-language test plans to
test-architect.
Validation Contract
Run from this skill directory before declaring changes complete:
python scripts/check.py
git diff --check
Completion criteria:
scripts/check.pyexits 0.git diff --checkexits 0.- No portable-CLI violations remain under this skill directory.
After changing skill definitions, public descriptions, reference files, or eval behavior, invoke docs-steward if available.
Critical Rules
- Reject Python setup advice that uses
pip install,uv pip install, or barepythonwhen the task is not explicitly on an approved exception path. - Require
uv addfor runtime dependencies anduv add --group devfor development-only dependencies unlessreferences/exceptions.mdjustifies a legacy or constrained-environment deviation. - Require
uv run ty checkfor type checking; do not recommendmypyor barety checkas the default path in this repo. - Treat
uv run ruff check,uv run ruff format,uv run ty check, anduv run pytestas the default completion gate for Python changes unless an exception is documented. - Do not edit
uv.lockby hand; useuv lock,uv sync, or dependency commands. - Do not present guided library preferences as mandatory replacements for an already-established local stack.
- Read
references/exceptions.mdbefore approving a legacy toolchain, alternate environment manager, or alternate library path. - Redirect mixed-language or non-Python-primary work through
references/redirection-boundaries.mdinstead of force-fitting this skill onto the whole task.
Canonical terms (use these exactly):
uv-- the required package manager and task runnerty-- the required type checker (not mypy)uv run ty check-- the required type-check commandruff-- the required linter and formatterpyproject.toml-- the single source of project configurationuv run-- prefix for all Python command executionuv sync --locked-- default reproducible install check for lockfile-backed workflows
Scaling Strategy
- 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, andreferences/exceptions.mdto separate hard violations from documented transition paths.
Progressive Disclosure
- Do not load every reference by default.
- Read
references/tooling-contract.mdfirst for command-sequence questions. - Read
references/redirection-boundaries.mdwhen shell, JS/TS, CI, or framework-specific work is mixed into the request. - Read
references/exceptions.mdonly when the task appears to require legacy, corporate, or constrained-environment exceptions. - Read
references/library-preferences.mdonly when selecting libraries for new Python work. - Read performance or testing references only when the active task actually touches those areas.
Scope Boundaries
IS for: Python tooling conventions, command selection, dependency-management rules, type/lint/test gates, and exception-aware repo guidance.
NOT for: JS/TS conventions, shell conventions, CI pipeline design, profiling investigations, test architecture, or framework/domain-specific implementation strategy.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wyattowalsh/agents/python-conventions">View python-conventions on skillZs</a>