Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts.
View on GitHubFebruary 1, 2026
Select agents to install to:
npx add-skill https://github.com/wshobson/agents/blob/main/plugins/python-development/skills/python-project-structure/SKILL.md -a claude-code --skill python-project-structureInstallation paths:
.claude/skills/python-project-structure/# 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 ``` myproject/ ├── src/ │ └── myproject/ │ ├── __init__.py │ ├── services/ │ ├── models/ │ └── api/ ├── tests/ ├── pyproject.toml └── README.md ``` ## Fundamental Patterns ### Pattern 1: One Concept Per File Each file should focus on a single concept or closely related set of functions. Consider splitting when a file: - Handles multiple unrelated responsibilities - Grows beyond 300-500 lines (varies by complexity) - Contains classes that change for different reasons ```python # Good: Focused files # user_service.py - User business logic # user_repository.py - User data access # user_models.py - User data structures # Avoid: Kitchen sink files # user.py - Contains service, repository, models, utilities... ``` ### Pattern 2: Explicit Public APIs with `__all__` Define the public interface for every module. Unlisted members are internal implementation details. ```python # mypackage/services/__init__.py from .user_service