{"id":"591132eb-8df5-46c5-aa4e-e508249ed883","shortId":"KX4uU2","kind":"skill","title":"python-monorepo","tagline":"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.","description":"# Python Monorepo with uv Workspaces\n\nModern Python monorepo architecture using `uv` for workspace management and `mise` for Python version and task orchestration.\n\n## Core Concepts\n\n**Monorepo**: Single repository containing multiple related packages and applications\n\n**uv workspace**: Python's answer to npm/pnpm workspaces\n- Single lock file for entire repo\n- Shared virtual environment\n- Cross-package dependency resolution\n\n## Directory Structure\n\n```\nmy-monorepo/\n├── .mise.toml           # Python version + task runner\n├── pyproject.toml       # Root workspace config\n├── uv.lock              # Unified lock file\n├── apps/                # Deployable applications\n│   ├── api/\n│   └── worker/\n└── packages/            # Shared libraries\n    ├── core/\n    └── utils/\n```\n\n## Workspace Configuration\n\n**Root pyproject.toml:**\n\n```toml\n[project]\nname = \"my-monorepo\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\n\n[tool.uv.workspace]\nmembers = [\"apps/*\", \"packages/*\"]\n\n[tool.uv]\ndev-dependencies = [\n    \"pytest>=8.0.0\",\n    \"ruff>=0.8.0\",\n    \"basedpyright>=1.0.0\",\n]\n```\n\nSee `references/workspace-config.md` for detailed configurations.\n\n## Package Linking\n\nWorkspace packages reference each other by distribution name:\n\n**packages/utils/pyproject.toml:**\n```toml\n[project]\nname = \"my-utils\"\ndependencies = [\"my-core\"]\n```\n\n**apps/api/pyproject.toml:**\n```toml\n[project]\nname = \"my-api\"\ndependencies = [\"my-core\", \"my-utils\", \"fastapi>=0.100.0\"]\n```\n\n## Cross-Package Import\n\n**packages/core/src/my_core/entities.py:**\n```python\nclass User:\n    def __init__(self, email: str):\n        self.email = email\n```\n\n**apps/api/src/my_api/main.py:**\n```python\nfrom my_core.entities import User  # Import from workspace package\n\ndef run():\n    # App code...\n```\n\n## Dependency Direction (Critical)\n\n```\napps/ → packages/  (Apps depend on packages)\npackages/ ⇏ apps/  (Never the reverse)\n```\n\n**Rules:**\n- Apps can depend on packages\n- Packages can depend on other packages\n- Packages NEVER depend on apps\n- Avoid circular dependencies\n\n## mise Task Runner\n\n**.mise.toml:**\n\n```toml\n[tools]\npython = \"3.12\"\n\n[tasks.check]\ndepends = [\"lint\", \"typecheck\", \"test\"]\n\n[tasks.lint]\nrun = \"uv run ruff check .\"\n```\n\n**Usage:** `mise run check`\n\n## Core uv Commands\n\n```bash\nuv sync                           # Install all packages\nuv add fastapi --package my-api   # Add to specific package\nuv add my-core --package my-api   # Add workspace package\nuv run pytest                      # Run tests\nuv lock --upgrade                 # Update dependencies\n```\n\n## Best Practices\n\n1. Single lock file at root\n2. Shared dev tools (ruff, pytest) in root dev-dependencies\n3. Pin Python version with mise\n4. Apps depend on packages only\n5. Use namespace packages for logical grouping (optional)\n\n## References\n\nFor detailed patterns:\n- `references/workspace-config.md` - pyproject.toml patterns, dependencies, versions\n- `references/docker.md` - Multi-stage Docker builds\n- `references/namespace-packages.md` - PEP 420 namespace packages","tags":["python","monorepo","atelier","martinffx","agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill"],"capabilities":["skill","source-martinffx","skill-python-monorepo","topic-agent-skills","topic-agentic-coding","topic-anthropic","topic-claude-code","topic-claude-skills","topic-code-review","topic-codex","topic-codex-skill","topic-opencode","topic-prompt-engineering","topic-sdd","topic-spec-driven-development"],"categories":["atelier"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/martinffx/atelier/python-monorepo","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add martinffx/atelier","source_repo":"https://github.com/martinffx/atelier","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 23 github stars · SKILL.md body (3,019 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:23.535Z","embedding":null,"createdAt":"2026-05-10T07:03:12.324Z","updatedAt":"2026-05-18T19:05:23.535Z","lastSeenAt":"2026-05-18T19:05:23.535Z","tsv":"'0.1.0':127 '0.100.0':187 '0.8.0':143 '1':318 '1.0.0':145 '2':324 '3':335 '3.12':131,258 '4':341 '420':372 '5':347 '8.0.0':141 'across':24 'add':284,290,295,303 'answer':70 'api':109,178,289,302 'app':30,106,134,215,220,222,227,232,247,342 'applic':65,108 'apps/api/pyproject.toml':172 'apps/api/src/my_api/main.py':203 'apps/packages':12 'architectur':6,41 'avoid':248 'basedpyright':144 'bash':277 'best':316 'build':369 'check':269,273 'circular':249 'class':194 'code':216 'command':276 'concept':56 'config':101 'configur':20,117,150 'contain':60 'core':55,114,171,182,274,298 'critic':219 'cross':84,189 'cross-packag':83,188 'def':196,213 'depend':23,86,139,168,179,217,223,234,239,245,250,260,315,334,343,362 'deploy':107 'design':27 'detail':149,357 'dev':138,326,333 'dev-depend':137,332 'direct':218 'directori':88 'distribut':159 'docker':368 'email':199,202 'entir':78 'environ':82 'fastapi':186,285 'file':76,105,321 'group':353 'import':191,207,209 'init':197 'instal':280 'librari':113 'link':152 'lint':261 'lock':75,104,312,320 'logic':352 'manag':22,46 'member':133 'mise':10,48,251,271,340 'mise.toml':93,254 'modern':38 'monorepo':3,5,34,40,57,92,125 'multi':29,366 'multi-app':28 'multi-stag':365 'multipl':61 'my-api':176,287,300 'my-cor':169,180,296 'my-monorepo':90,123 'my-util':165,183 'my_core.entities':206 'name':122,160,164,175 'namespac':349,373 'never':228,244 'npm/pnpm':72 'option':354 'orchestr':54 'packag':25,63,85,111,135,151,154,190,212,221,225,226,236,237,242,243,282,286,293,299,305,345,350,374 'packages/core/src/my_core/entities.py':192 'packages/utils/pyproject.toml':161 'pattern':13,358,361 'pep':371 'pin':336 'practic':317 'project':18,121,163,174 'pyproject.toml':98,119,360 'pytest':140,308,329 'python':2,4,31,33,39,50,68,94,130,193,204,257,337 'python-monorepo':1 'refer':155,355 'references/docker.md':364 'references/namespace-packages.md':370 'references/workspace-config.md':147,359 'relat':62 'repo':79 'repositori':32,59 'requir':129 'requires-python':128 'resolut':87 'revers':230 'root':99,118,323,331 'ruff':142,268,328 'rule':231 'run':214,265,267,272,307,309 'runner':97,253 'see':146 'self':198 'self.email':201 'set':16 'share':80,112,325 'singl':58,74,319 'skill' 'skill-python-monorepo' 'source-martinffx' 'specif':292 'stage':367 'str':200 'structur':19,89 'sync':279 'task':53,96,252 'tasks.check':259 'tasks.lint':264 'test':263,310 'toml':120,162,173,255 'tool':256,327 'tool.uv':136 'tool.uv.workspace':132 'topic-agent-skills' 'topic-agentic-coding' 'topic-anthropic' 'topic-claude-code' 'topic-claude-skills' 'topic-code-review' 'topic-codex' 'topic-codex-skill' 'topic-opencode' 'topic-prompt-engineering' 'topic-sdd' 'topic-spec-driven-development' 'typecheck':262 'unifi':103 'updat':314 'upgrad':313 'usag':270 'use':14,42,348 'user':195,208 'util':115,167,185 'uv':8,36,43,66,266,275,278,283,294,306,311 'uv.lock':102 'version':51,95,126,338,363 'virtual':81 'worker':110 'workspac':9,21,37,45,67,73,100,116,153,211,304","prices":[{"id":"3d8a9486-2902-4c57-b0a8-54b780c505f8","listingId":"591132eb-8df5-46c5-aa4e-e508249ed883","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"martinffx","category":"atelier","install_from":"skills.sh"},"createdAt":"2026-05-10T07:03:12.324Z"}],"sources":[{"listingId":"591132eb-8df5-46c5-aa4e-e508249ed883","source":"github","sourceId":"martinffx/atelier/python-monorepo","sourceUrl":"https://github.com/martinffx/atelier/tree/main/skills/python-monorepo","isPrimary":false,"firstSeenAt":"2026-05-10T07:03:12.324Z","lastSeenAt":"2026-05-18T19:05:23.535Z"}],"details":{"listingId":"591132eb-8df5-46c5-aa4e-e508249ed883","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"martinffx","slug":"python-monorepo","github":{"repo":"martinffx/atelier","stars":23,"topics":["agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill","opencode","prompt-engineering","sdd","spec-driven-development"],"license":"mit","html_url":"https://github.com/martinffx/atelier","pushed_at":"2026-05-18T06:56:45Z","description":"An atelier for Opencode, Claude Code, and other coding agents: spec-driven workflows, deep thinking, and code quality.","skill_md_sha":"5319708902bf38ad8b8a236e488aa51b4977e05e","skill_md_path":"skills/python-monorepo/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/martinffx/atelier/tree/main/skills/python-monorepo"},"layout":"multi","source":"github","category":"atelier","frontmatter":{"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."},"skills_sh_url":"https://skills.sh/martinffx/atelier/python-monorepo"},"updatedAt":"2026-05-18T19:05:23.535Z"}}