python-monorepo-architecture — SKILL.md

Variant: standard · When to use: architecting the cross-package structure of a multi-package Python uv-workspace monorepo.

Overview

This skill is about the cross-package layer of a Python monorepo: a single repository holding several installable packages (members) managed by a uv workspace — typically one shared library plus one or more application or CLI members that build on it. It covers the decisions that live between packages: where the lib/app boundary goes, which way dependencies are allowed to point, how to keep the boundary honest when the tool can't, what each member exposes to the others, where shared tests live, and how to carve a shared library out of an existing package without breaking it. It does not re-teach intra-package module layout (__all__, layered structure — that is the python-project-structure skill) or general uv usage (uv add/uv run — the uv skill); it owns the uv-workspace wiring because those skills do not cover it, and it composes with both.

When to activate

• ✅ Deciding whether to split a growing codebase into a shared libs/<core> plus apps/<app> / tools/<cli> members, or keep it one package.
• ✅ Wiring a uv workspace where one member depends on another (the shared library).
• ✅ Diagnosing or preventing a circular import / tangled dependency between packages.
• ✅ Extracting shared logic out of an app or CLI package into a new shared library.
• ✅ Deciding what a member's public API at the package boundary should be, and how consumers import it.

Do NOT activate when: