Python Standard Workflow

Overview

Use this skill to turn Python work into a repeatable, tool-driven workflow based on uv, ruff, typos, and mypy. Prefer it when the user wants a consistent Python project baseline rather than an ad hoc one-off fix.

Use This Skill When

• Bootstrapping a new Python repository
• Migrating a Python repo from loose pip commands to uv
• Adding or repairing ruff, typos, or mypy configuration
• Making a Python codebase pass quality gates before handoff or review

Do Not Use This Skill When

• The task is not Python-focused
• The repository already has a different mandated workflow and the user did not ask to migrate it
• The request is a narrow logic change that does not require toolchain work

Workflow

1. Inspect Before Changing

Read the existing project shape first:

• pyproject.toml
• .python-version
• uv.lock
• source layout such as src/, package directories, and tests/
• existing lint, spellcheck, or type-check config files

Do not blindly replace an established workflow. If the repo already uses uv, extend it. If it uses another package manager and the user did not ask to migrate, work within the existing choice.

2. Standardize on uv

Prefer a uv-managed workflow for Python dependency and command execution.

• If uv is already present, keep using it.
• If uv is missing, install it using an approved official method for the environment.
• Prefer uv add --dev ... over raw pip install for project-scoped developer tooling.
• Do not run uv init blindly inside an existing repository; only initialize when the project is actually missing a package manifest.

Typical developer tooling command:

uv add --dev ruff typos mypy

3. Configure the Quality Tools

Set up a baseline that is strict enough to be useful and light enough to adopt.

Ruff

• Use Ruff for both formatting and linting.
• Match target-version to the project's actual Python version.
• Start with a practical lint set such as E, F, I, B, and UP.
• Avoid adding broad ignores unless the failure is understood and documented.

Typos

• Run typos across the repository, but exclude generated, vendored, and lockfile content.
• Only add custom allowed words when the term is intentionally project-specific.

MyPy

• Prefer real type checking over silencing errors.
• On legacy repositories, scope MyPy to the maintained package or src/ tree first, then expand.
• Use ignores sparingly and only when the boundary is external or intentionally dynamic.

4. Run the Gate in a Fixed Order

Use the bundled script scripts/run_quality_gate.sh when possible. The default gate order is:

1. uv run ruff format --check
2. uv run ruff check
3. uv run typos
4. uv run mypy

This order keeps the fast autofix and syntax feedback first, then spelling, then the slower type analysis.

5. Fix Failures, Then Re-Run

• Prefer code fixes over configuration suppression.
• If ruff format --check fails, format before reasoning about lint noise.
• If ruff check reports import sorting or upgradeable syntax, accept the standardized rewrite.
• If typos reports a real typo, fix the source; do not whitelist accidental misspellings.
• If mypy fails broadly on a legacy repository, reduce the checked surface intentionally and note that scope in the final result.

6. Completion Criteria

Do not report success until the quality gate passes or the user explicitly accepts scoped exceptions.

Minimum completion bar:

• uv is the command runner for the workflow
• ruff, typos, and mypy are configured or intentionally scoped
• the chosen validation commands complete successfully
• any remaining exclusions or ignores are deliberate and explained

Default Commands

For a typical repository:

uv add --dev ruff typos mypy
uv run ruff format --check .
uv run ruff check .
uv run typos .
uv run mypy .

For a legacy repository with a narrower type-check target:

uv run mypy src

Reference Files

• Read references/pyproject-template.md when you need a baseline pyproject.toml layout for uv, ruff, typos, and mypy.
• Use scripts/run_quality_gate.sh when you want a single repeatable command for the full quality gate.