python-package-development

A skill for building Python packages with the philosophy of the R package ecosystem: clear user communication, principled API design, living documentation, and ceremonial lifecycle management.

The guiding question for every decision: "What would make this package feel like a thoughtful, professional tool — not just a collection of functions?"

How This Skill Is Organized

This SKILL.md gives you the philosophy and the map. For implementation details, read the relevant reference file from

references/

Read only what's relevant to the current task. Don't load everything at once.

The Five Principles

Before touching any reference file, internalize these. They inform every decision.

1. User communication is a first-class concern

Every message a user sees — errors, warnings, progress, success — should be intentional. Use

rich

cli

rich

2. Function names form a grammar

Names should be guessable. Use

verb_noun()

read_parquet()

read_csv()

3. Lifecycle deserves ceremony

Deprecations are promises to users. When something changes, warn early, warn clearly, and give users a path forward. Never silently break things. Never deprecate without a timeline.

4. Documentation lives next to code

Docstrings are not optional and not a final step. They are written at the same time as the function. Use Google style consistently.

mkdocstrings

5. There is a whole game

A user should be able to see a complete, working package early — not after mastering every detail. Scaffold first, refine later.

Anatomy of a Well-Structured Package

my-package/
├── pyproject.toml          ← single source of truth (uv-managed)
├── README.md               ← the story and quickstart
├── CHANGELOG.md            ← user-facing version history
├── mkdocs.yml              ← docs config (project root, not inside docs/)
├── src/
│   └── my_package/
│       ├── __init__.py     ← clean public API surface
│       ├── py.typed         ← PEP 561 marker for type checkers
│       ├── errors.py       ← structured exception hierarchy (public contract)
│       ├── _messages.py    ← rich console, message helpers
│       └── core.py         ← actual logic
├── tests/
│   ├── conftest.py         ← shared fixtures
│   └── test_core.py
└── docs/
    ├── index.md
    └── api.md

Key decisions encoded here:

• src layout always — prevents accidental imports from the project root

• errors.py

  is always its own file — errors are a public contract (no underscore: users import these directly)

• _messages.py

  centralizes all user-facing output — never scattered

  print()

  calls

• __init__.py

  is curated, not auto-imported — users see only what's intentional

Argument Routing

When invoked with

/python-package-development <subcommand>

/python-package-development scaffold <name>

<name>

/python-package-development api

/python-package-development test

/python-package-development docs

/python-package-development lifecycle

/python-package-development release

/python-package-development check

python ${CLAUDE_SKILL_DIR}/../../scripts/check-structure.py .

/python-package-development pre-commit

/python-package-development cli

/python-package-development

When invoked without a subcommand (auto-triggered or plain

/python-package-development

Step 1 — Automated audit. Run the convention checker if available:

python ${CLAUDE_SKILL_DIR}/../../scripts/check-structure.py .

Step 2 — Manual review of things the script can't check:

1. Naming — Do public functions follow

   verb_noun()

   ? Are families consistent?
2. Documentation — Do all public functions have Google-style docstrings with Args/Returns/Raises?
3. Messages — Is

   _messages.py

   actually used? Any bare

   print()

   calls?
4. Lifecycle — Is

   __version__

   from

   importlib.metadata

   ? Any undocumented breaking changes?

Step 3 — Suggest improvements using the Quick Decision Guide below.

Quick Decision Guide

User asks to scaffold / create a new package: → Read references/01-scaffold.md. Walk through the whole game first.

User asks about function names, API shape, or error messages: → Read references/02-api-design.md. Apply naming conventions and message hierarchy.

User asks about tests or is writing test code: → Read references/03-testing.md. Enforce pytest conventions and fixture patterns.

User asks about docs, docstrings, or mkdocs: → Read references/04-docs.md. Enforce Google docstrings and mkdocs-material setup.

User mentions deprecating something, versioning, or breaking changes: → Read references/05-lifecycle.md. Apply the deprecation ceremony.

User wants to publish, release, or set up CI: → Read references/06-release.md. Walk through PyPI + GitHub Actions setup.

Multiple concerns at once: → Read the most relevant reference first. Reference others by name when needed.

Common Mistakes — Catch These Early

When reviewing or generating Python package code, watch for these. If you see any, fix them immediately and explain why.

src/

src/

from .module import *

__init__.py

__all__

--cov=src

--cov=my_package

dependencies = ["requests"]

"requests>=2.28"

dependencies = ["requests>=2.28,<3"]

requires-python = ">=3.10,<3.13"

">=3.10"

__version__ = "0.1.0"

importlib.metadata.version()

py.typed

touch src/my_package/py.typed

print()

_messages.py

rich

raise Exception("bad")

errors.py

[project] dependencies

[dependency-groups]

tests/__init__.py

conftest.py

MANIFEST.in

"requests==2.31.0"

mkdocs.yml

docs/

mkdocs serve

mkdocs.yml

For the full list with detailed explanations, see references/07-common-mistakes.md.

Tone When Helping

• Be opinionated. This skill exists to have opinions. Don't offer five options when one is right.
• Explain the why behind conventions, especially when they come from the R world.
• When translating an R concept to Python, name the translation explicitly:

  "This is the Python equivalent of rlang::abort() — here's how it maps."

• Push back gently on anti-patterns (scattered

  print()

  , flat structure, inconsistent names) but always offer the better path immediately.