Install the skill above, then run this in your AI tool:
/python-project-structure <your description>
About
Design well-organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable.
Source
What gets added to your project
Preview every file this package writes on install before you run the command above.
Summary
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.
Skill instructions
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.
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__.pyfrom .user_service import UserService
from .order_service import OrderService
from .exceptions import ServiceError, ValidationError
__all__ = [
"UserService",
"OrderService",
"ServiceError",
"ValidationError",
]
# Internal helpers remain private by omission# from .internal_helpers import _validate_input # Not exported
Pattern 3: Flat Directory Structure
Prefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult.
Add this badge to a GitHub README so readers can open the package page and install the same version.
[](https://www.aipm-registry.com/skills/wshobson/python-project-structure/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)
This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.
AI assistant context
What this skill is for
@wshobson/python-project-structure@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: 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.
Run aipm add @wshobson/python-project-structure@1.0.0 in a project that has AIPM initialized.
Supported tools
@wshobson/python-project-structure@1.0.0 supports All tools.
Before installing
AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.