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:
Standards over convention — Follow PEPs and official PyPA guidance, not tribal knowledge.
pyproject.tomloversetup.py, PEP 621 over custom metadata, PEP 735 over ad-hoc dev dependencies.Tooling-enforced — Every rule must be enforced by a tool. Ruff for linting/formatting, mypy for types, pytest with
fail_underfor coverage, GitHub Actions for CI. If a human has to remember it, it will be forgotten.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.
Source: oborchers/fractional-cto — distributed by TomeVault.