Split Python style skill into focused modules

python-project-defaults/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: python-project-defaults
+description: 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`.
+
+```python
+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.
+
+```python
+# 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.

python-project-defaults/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Python Project Defaults"
+  short_description: "Repo-aligned Python defaults"
+  default_prompt: "Apply the user's Python defaults while preserving repository conventions. Only introduce uv, click, or basedpyright when the repo already uses them, the task is greenfield, or the user explicitly asks to standardize on them."