skill-python-style-preferences/python-project-defaults/SKILL.md

name, description

name	description
python-project-defaults	Apply repo-aligned Python defaults for greenfield modules, scaffolding, CLIs, libraries, and typed implementation work in projects that already use or are explicitly standardizing on uv, click, and comprehensive typing. Do not use for general code review or to migrate existing projects away from their current tooling unless requested.

Python Project Defaults

Use this skill to apply the user's preferred Python defaults without turning an implementation task into a tooling migration.

Priority Order

1. Explicit user instructions
2. Existing repository conventions and verification workflow
3. This skill

These are defaults, not mandatory migrations.

Do not switch a repository to uv, click, or basedpyright unless:

• the repository already uses it
• the task is greenfield or scaffolding
• the user explicitly asks to standardize on it

Skip this skill for general code review unless the user explicitly wants style-standardization feedback.

Before Applying This Skill

Check the local project first:

• packaging and environment: pyproject.toml, requirements*, lockfiles, existing env tooling
• task runner and verification flow: Makefile, justfile, tox.ini, noxfile.py, CI commands
• CLI framework: click, typer, argparse, or no CLI
• type checker: basedpyright, pyright, mypy, or no configured checker
• data modeling patterns: TypedDict, dataclass, pydantic, attrs, ORM models

If the repository already uses an alternative, keep it. Mirror the repo before introducing new tooling.

Core Defaults

Use these defaults when the repository is already aligned with them or the task is greenfield.

1. Start with typed domain shapes.

• Prefer TypedDict for reusable mapping-shaped payloads when the repo does not already favor another model layer.
• Prefer @dataclass(slots=True) for reusable owned records and value objects when that matches local conventions.
• Avoid reusable bare dict[str, object] structures; keep ad hoc dicts local and short-lived.

2. Keep entrypoints thin.

• Put parsing and CLI wiring in the repo's existing CLI framework.
• Put business logic in typed functions and classes.
• If you are creating a new CLI with no established framework, default to click.

from pathlib import Path

import click


@click.command()
@click.argument("config_path", type=click.Path(path_type=Path))
def main(config_path: Path) -> None:
    run(config_path)


def run(config_path: Path) -> None:
    ...

3. Treat typing as enforcement, not decoration.

• Annotate public functions, methods, return values, and reusable internal helpers.
• Use the repository's configured type checker. If the repo has no established checker and the task is greenfield, default to basedpyright.
• Allow cast(...) only at trusted boundaries where runtime guarantees exist but inference cannot express them. Leave a short reason comment immediately above it.
• Allow # type: ignore[...] only when it is narrow and justified. Leave a short reason comment immediately above it.

# basedpyright cannot infer the validated plugin registry value type here.
runner = cast(Runner, registry[name])

# The vendor stub is wrong for this overload; runtime input is validated above.
value = vendor_api.load(path)  # type: ignore[call-overload]

Verification

Use the repository's existing verification workflow first.

Examples:

• make test
• just test
• tox -e py
• nox -s tests
• poetry run pytest
• hatch run test
• the project's documented CI wrapper commands

If no local workflow exists and the task is greenfield or already aligned with this stack, use this fallback order:

1. uv sync --dev
2. uv run basedpyright
3. uv run pytest
4. uv run python -m <package_or_module> or a CLI smoke test when relevant

Anti-Goals

• Do not change a repository's package manager or lockfile format unless asked.
• Do not replace an existing CLI framework with click unless asked.
• Do not let style preferences override correctness, bug fixing, or the user's explicit task.
• Do not treat this skill as a mandate to rewrite working code that already matches local conventions.