Python Project Structure
Helps you organize Python codebases with clear module boundaries and explicit public APIs. Covers directory layout decisions, when to use `__all__` for interface definition, flat vs nested structures, and test file placement strategies. Good for starting new projects or refactoring messy ones where imports are confusing and module responsibilities are blurred. The layered vs domain-driven organization patterns are solid, and the guidance on keeping files focused while avoiding deep nesting will save you from the typical "where does this code belong" paralysis that kills productivity.
- install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.
- 9
- skills.sh installs
- 15.4K
- GitHub stars
- 42.4K
- last updated
- Aug 21, 2026
Install
$ npx -y skills add wshobson/agents --skill python-project-structure --agent claude-codeInstalls into .claude/skills of the current project.
Files
Python Project Structure & Module Architecture
Design well-organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable.
When to Use This Skill
- Starting a new Python project from scratch
- Reorganizing an existing codebase for clarity
- Defining module public APIs with
__all__ - Deciding between flat and nested directory structures
- Determining test file placement strategies
- Creating reusable library packages
Core Concepts
1. Module Cohesion
Group related code that changes together. A module should have a single, clear purpose.
2. Explicit Interfaces
Define what's public with __all__. Everything not listed is an internal implementation detail.
3. Flat Hierarchies
Prefer shallow directory structures. Add depth only for genuine sub-domains.
4. Consistent Conventions
Apply naming and organization patterns uniformly across the project.
Quick Start
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageDetails
- Repository
- github.com/wshobson/agents
- Categories
- Backend & APIs, Code Review & Quality, Productivity & Planning, Python, Design & UI/UX
More from wshobson/agents
All 174- Accessibility Compliance15.2K
- K8s Security Policies15.1K
- Monorepo Management15K
- Python Error Handling14.7K
- Rag Implementation14.4K
- Deployment Pipeline Design14.2K
- Changelog Automation14.2K
- Bash Defensive Patterns14.1K
- Visual Design Foundations14.1K
- Debugging Strategies13.9K
- Python Anti Patterns13.8K
- Stripe Integration13.8K
- Microservices Patterns13.7K
- Secrets Management13.6K
- Web Component Design13.6K
- Gitlab Ci Patterns13.6K
- Grafana Dashboards13.6K
- Langchain Architecture13.6K
- Protocol Reverse Engineering13.5K
- Python Packaging13.4K
- Llm Evaluation13.3K
- Python Type Safety13.2K
- Startup Financial Modeling13.1K
- React Modernization13.1K
Recommended
More Backend & APIs
fastapifastapi/fastapiFastAPI best practices and conventions. Use when working with FastAPI APIs, Pydantic models, dependencies, streaming responses including Server-Sent Events (SSE14.9Kskills.sh installs
clerk-vue-patternsclerk/skillsVue 3 patterns with Clerk — composables (useAuth, useUser, useClerk, useOrganization), Vue Router guards, Pinia auth store integration. Triggers on: vue clerk, 14.5Kskills.sh installs
microsoft-code-referencegithub/awesome-copilotLook up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs14.4Kskills.sh installs
email-best-practicesresend/resend-skillsUse when building email features, emails going to spam, high bounce rates, setting up SPF/DKIM/DMARC authentication, implementing email capture, ensuring compli14.2Kskills.sh installsresend-cliresend/resend-skillsOperate the Resend platform from the terminal — send emails (including React Email .tsx templates via --react-email), manage domains, contacts, broadcasts, temp14Kskills.sh installs
upgrading-react-nativecallstackincubator/agent-skillsUpgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android conf13.7Kskills.sh installs