using-python-package-principles

name	using-python-package-principles
description	This skill should be used when the user asks "which Python packaging skill should I use", "show me all Python package principles", "help me set up a Python project", or at the start of any Python package creation, review, or modernization task. Provides the index of all 12 principle skills.
version	1.0.0

When creating, reviewing, or modernizing any Python package — setting up project structure, configuring pyproject.toml, adding type hints, writing tests, building CI/CD pipelines, writing docs, releasing versions, designing APIs, packaging for distribution, securing the supply chain, or improving developer experience — invoke the relevant python-package skill BEFORE proceeding.

These are not suggestions. They are research-backed standards drawn from FastAPI, Pydantic, httpx, Ruff, uv, Polars, Rich, pytest, Hatch, Flask, attrs, Django, and 30+ PEPs.

How to Access Skills

Use the Skill tool to invoke any skill by name. When invoked, follow the skill's guidance directly.

Python Package Principles

Skill	Triggers On
python-package:project-structure	src/ vs flat layout, directory organization, __init__.py design, _internal/ convention, py.typed marker, monorepo vs single-package
python-package:pyproject-toml	pyproject.toml configuration, PEP 621 metadata, build backends (hatchling/setuptools/flit/maturin), PEP 735 dependency groups, PEP 639 SPDX licenses, dynamic versioning, entry points
python-package:code-quality	Ruff configuration, mypy strict mode, modern type hints (PEP 695/649), str | None vs Optional, pre-commit hooks, formatting rules
python-package:testing-strategy	pytest configuration, test organization, fixtures, parametrize, coverage (80-90%), async testing, Hypothesis, nox/tox, snapshot testing
python-package:ci-cd	GitHub Actions workflows, test matrix, trusted publishing (OIDC), release automation, caching, Dependabot/Renovate, SLSA/Sigstore, reusable workflows
python-package:documentation	MkDocs Material vs Sphinx, mkdocstrings/Griffe, Diataxis framework, Google-style docstrings, versioned docs, code examples in docs
python-package:versioning-releases	SemVer vs CalVer, PEP 440, Keep a Changelog, Towncrier, Conventional Commits, release process, deprecation strategy
python-package:cli-architecture	CLI framework selection (Click/Typer/argparse), cli.py vs cli/ directory, __main__.py delegation, exit codes, [project.scripts] entry points, subcommand organization
python-package:api-design	Public API surface (__all__), progressive disclosure, exception hierarchy, async/sync dual API, plugin architecture (pluggy/entry points/protocols), dependency injection
python-package:packaging-distribution	Pure Python vs compiled extensions, wheel format, platform tags, maturin/scikit-build-core, cibuildwheel, package size, namespace packages
python-package:security-supply-chain	Trusted publishing (OIDC), Sigstore/PEP 740, SLSA framework, pip-audit, SECURITY.md, dependency scanning, OpenSSF Scorecard
python-package:developer-experience	One-command dev setup, CONTRIBUTING.md, Makefile/justfile, issue/PR templates, code of conduct, governance models, README best practices

When to Invoke Skills

Invoke a skill when there is even a small chance the work touches one of these areas:

• Creating a new Python package from scratch
• Modernizing an existing package (setup.py to pyproject.toml, adding typing, upgrading CI)
• Reviewing a package for best practices compliance
• Setting up testing, CI/CD, or documentation
• Preparing a release or publishing to PyPI
• Designing a library's public API
• Hardening supply chain security

The Three Meta-Principles

All principles rest on three foundations:

1. Standards over convention — Follow PEPs and official PyPA guidance, not tribal knowledge. pyproject.toml over setup.py, PEP 621 over custom metadata, PEP 735 over ad-hoc dev dependencies.

2. Tooling-enforced — Every rule must be enforced by a tool. Ruff for linting/formatting, mypy for types, pytest with fail_under for coverage, GitHub Actions for CI. If a human has to remember it, it will be forgotten.

3. Exemplar-validated — Every recommendation is validated against real-world exemplar packages (FastAPI, Pydantic, httpx, Ruff, uv, Polars). If the best packages don't do it, neither should you.