martinffx/python-monorepo
skills/python-monorepo/SKILL.md
Python monorepo architecture with uv workspaces, mise, and apps/packages pattern. Use when setting up project structure, configuring workspaces, managing dependencies across packages, or designing multi-app Python repositories.
$ install --global
skillsauthnpx skillsauth add martinffx/claude-code-atelier python-monorepoInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 26, 2026, 1:04 PM38.2s4 files scanned
SKILL.md
- name:
- python-monorepo
- description:
- Python monorepo architecture with uv workspaces, mise, and apps/packages pattern. Use when setting up project structure, configuring workspaces, managing dependencies across packages, or designing multi-app Python repositories.
- user-invocable:
- false
Python Monorepo with uv Workspaces
Modern Python monorepo architecture using uv for workspace management and mise for Python version and task orchestration.
Core Concepts
Monorepo: Single repository containing multiple related packages and applications
uv workspace: Python's answer to npm/pnpm workspaces
- Single lock file for entire repo
- Shared virtual environment
- Cross-package dependency resolution
Directory Structure
my-monorepo/
├── .mise.toml # Python version + task runner
├── pyproject.toml # Root workspace config
├── uv.lock # Unified lock file
├── apps/ # Deployable applications
│ ├── api/
│ └── worker/
└── packages/ # Shared libraries
├── core/
└── utils/
Workspace Configuration
Root pyproject.toml:
[project]
name = "my-monorepo"
version = "0.1.0"
requires-python = ">=3.12"
[tool.uv.workspace]
members = ["apps/*", "packages/*"]
[tool.uv]
dev-dependencies = [
"pytest>=8.0.0",
"ruff>=0.8.0",
"basedpyright>=1.0.0",
]
See references/workspace-config.md for detailed configurations.
Package Linking
Workspace packages reference each other by distribution name:
packages/utils/pyproject.toml:
[project]
name = "my-utils"
dependencies = ["my-core"]
apps/api/pyproject.toml:
[project]
name = "my-api"
dependencies = ["my-core", "my-utils", "fastapi>=0.100.0"]
Cross-Package Import
packages/core/src/my_core/entities.py:
class User:
def __init__(self, email: str):
self.email = email
apps/api/src/my_api/main.py:
from my_core.entities import User # Import from workspace package
def run():
# App code...
Dependency Direction (Critical)
apps/ → packages/ (Apps depend on packages)
packages/ ⇏ apps/ (Never the reverse)
Rules:
- Apps can depend on packages
- Packages can depend on other packages
- Packages NEVER depend on apps
- Avoid circular dependencies
mise Task Runner
.mise.toml:
[tools]
python = "3.12"
[tasks.check]
depends = ["lint", "typecheck", "test"]
[tasks.lint]
run = "uv run ruff check ."
Usage: mise run check
Core uv Commands
uv sync # Install all packages
uv add fastapi --package my-api # Add to specific package
uv add my-core --package my-api # Add workspace package
uv run pytest # Run tests
uv lock --upgrade # Update dependencies
Best Practices
- Single lock file at root
- Shared dev tools (ruff, pytest) in root dev-dependencies
- Pin Python version with mise
- Apps depend on packages only
- Use namespace packages for logical grouping (optional)
References
For detailed patterns:
references/workspace-config.md- pyproject.toml patterns, dependencies, versionsreferences/docker.md- Multi-stage Docker buildsreferences/namespace-packages.md- PEP 420 namespace packages
Related Skills
martinffx/oracle-security
development
VerifiedTrustedCommunity
Security architecture and threat modeling knowledge. Auto-invokes when designing features that handle untrusted data, authentication, authorization, external integrations, file uploads, or sensitive data. Provides risk assessment frameworks, trust boundary analysis, and security design principles — not implementation code.
25SKILL.mdUpdated May 24, 2026
martinffx/oracle-doubt
testing
VerifiedTrustedCommunity
Adversarial review of non-trivial decisions using fresh-context scrutiny. Use when correctness matters more than speed, when stakes are high (production, security-sensitive logic, irreversible operations), or before committing significant architectural or implementation choices.
25SKILL.mdUpdated May 24, 2026
martinffx/code-handoff
development
VerifiedTrustedCommunity
Compact the current conversation into a handoff document for another agent to pick up.
25SKILL.mdUpdated May 24, 2026
martinffx/oracle-grillme
testing
VerifiedTrustedCommunity
Socratic interrogation of plans against the project's domain model and documented decisions. Use when the user wants to stress-test a plan, clarify terminology, or validate assumptions against existing domain language. Updates CONTEXT.md and ADRs inline as decisions crystallise.
25SKILL.mdUpdated May 23, 2026