python-package

Audit an entire Python package repository for best-practice compliance — systematically scans the codebase for structure, configuration, typing, testing, CI/CD, documentation, and security issues

Review the current Python package for best-practice violations — project structure, pyproject.toml, typing, testing, CI/CD, documentation, versioning, API design, packaging, security, and developer experience

Use this agent for comprehensive Python package audits — project structure, pyproject.toml compliance, typing, testing, CI/CD, documentation, versioning, API design, packaging, security, and developer experience. Handles both targeted file reviews and full repository audits. Examples: <example>Context: User has a Python package and wants it reviewed for best practices. user: "Review my Python package for best practices" assistant: "I'll use the package-reviewer agent to audit the package." <commentary>Package review for best practices touches all 11 principle areas — comprehensive audit needed.</commentary></example> <example>Context: User wants to check their pyproject.toml and CI setup before publishing. user: "Check if my package is ready to publish to PyPI" assistant: "I'll use the package-reviewer agent to check publishing readiness." <commentary>Publishing readiness review covers pyproject.toml, packaging, CI/CD, security, versioning — comprehensive audit.</commentary></example> <example>Context: User wants to modernize a legacy Python package. user: "Audit my package and tell me what needs to be modernized" assistant: "I'll use the package-reviewer agent to perform a modernization audit." <commentary>Modernization audit requires discovering legacy patterns (setup.py, missing types, old CI) and recommending upgrades across all areas.</commentary></example>

This skill should be used when the user is designing a library's public API surface, defining __all__, organizing imports, creating an exception hierarchy, implementing async/sync dual APIs, adding plugin architecture (pluggy, entry points, protocols), applying progressive disclosure, choosing return types, naming methods, or reviewing backward compatibility. Covers __all__, underscore-prefixed modules, exception trees, httpx _BaseClient pattern, pluggy, entry points, Protocols, dependency injection, configuration patterns.

This skill should be used when the user is setting up GitHub Actions, configuring CI/CD pipelines, creating test matrices, enabling trusted publishing with OIDC, automating PyPI releases, adding Dependabot or Renovate, or configuring Sigstore attestations. Covers workflow architecture, lint/type-check/test/build/publish jobs, caching, concurrency, reusable workflows, SLSA provenance.

This skill should be used when the user is adding a CLI to a Python package, choosing between Click, Typer, and argparse, structuring cli.py or a cli/ directory, creating a __main__.py for python -m support, defining console script entry points, handling exit codes, or organizing subcommands. Covers framework selection, CLI module layout, __main__.py delegation pattern, exit code conventions, and subcommand organization.

This skill should be used when the user is configuring Ruff, setting up mypy, adding type hints, choosing between mypy and pyright, writing py.typed markers, modernizing type annotations (PEP 695/649), using TYPE_CHECKING, setting up pre-commit hooks, configuring ruff format, choosing lint rule sets, or reviewing code quality tooling. Covers Ruff rule sets, mypy strict mode, pyright, modern typing patterns, pre-commit configuration, formatting, and complexity thresholds.

This skill should be used when the user is writing a CONTRIBUTING.md, setting up developer onboarding, creating a Makefile or justfile, adding issue templates, adding PR templates, writing a README, creating a CODE_OF_CONDUCT.md, setting up CODEOWNERS, adding .editorconfig, configuring devcontainers, labeling good first issues, or building project community and governance. Covers one-command dev setup, task automation, contributor funnel, and community health files.

This skill should be used when the user is setting up MkDocs Material, configuring mkdocstrings, writing docstrings, generating API reference pages, structuring documentation with the Diataxis framework, deploying docs to GitHub Pages or ReadTheDocs, or writing a README. Covers mkdocs.yml configuration, Griffe, Google-style docstrings, versioned docs with mike, code example testing, nav structure.

This skill should be used when the user is building wheels, creating sdists, packaging compiled extensions, configuring cibuildwheel, setting up maturin for Rust extensions, using scikit-build-core, optimizing package size, working with platform tags, namespace packages, or choosing between pure Python and compiled distributions. Covers wheel format, abi3 stable ABI, manylinux/musllinux tags, dual-package strategy, environment markers, PyPI metadata, and TestPyPI.

This skill should be used when the user is setting up a Python project structure, choosing between src/ and flat layout, organizing __init__.py files, creating a new package directory, or structuring a monorepo. Covers src/ layout, flat layout, __init__.py design, __all__ exports, _internal/ convention, py.typed marker, naming conventions, test placement, root-level files, and monorepo vs single-package patterns.

This skill should be used when the user is configuring pyproject.toml, choosing a build backend, declaring dependencies, setting up dependency groups, configuring tool settings, defining entry points, or managing package versioning. Covers PEP 621 metadata, hatchling vs setuptools vs flit-core vs maturin, PEP 735 dependency groups, PEP 639 SPDX licenses, dynamic versioning with hatch-vcs, dependency version constraints, console scripts, and tool configuration consolidation.

This skill should be used when the user is setting up trusted publishing, configuring OIDC for PyPI, enabling Sigstore attestations, writing a SECURITY.md, running pip-audit, scanning for vulnerabilities, configuring Dependabot or Renovate, setting up CodeQL, working with OpenSSF Scorecard, enabling 2FA on PyPI, defending against typosquatting, or hardening CI permissions. Covers PEP 740, SLSA framework, SPDX license compliance (PEP 639), and supply chain security best practices.

This skill should be used when the user is configuring pytest, writing tests, setting up test fixtures, using parametrize, measuring code coverage, writing async tests with pytest-asyncio, using Hypothesis for property-based testing, choosing between nox and tox, building CI test matrices, setting up snapshot testing with syrupy, mocking with pytest-mock, or reviewing test organization. Covers pytest configuration, fixtures, coverage thresholds, async testing, Hypothesis profiles, CI matrices, and mocking best practices.

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.

This skill should be used when the user is choosing a versioning scheme, writing a changelog, preparing a release, configuring Towncrier or python-semantic-release, planning deprecations, managing major version migrations, or setting up version single-source-of-truth. Covers SemVer, CalVer, PEP 440, Keep a Changelog, Towncrier, Conventional Commits, deprecation strategy, pre-release publishing, and release automation.

1 hook across 1 event