Agent skill · software engineering · wshobson
python-project-structure
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.
Why this skill is useful
Codifies project organization standards and module architecture practices that the AI could infer but now doesn't have to guess.
What it needs
About 3k tokens when loaded. Last updated 2026-08-05. 38,570 stars on the source repository.
What this skill does
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 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 Pattern 2: Explicit Public APIs with all Define the public interface for every module. Unlisted members are internal implementation details. Pattern 3: Flat Directory Structure Prefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult. Add sub-packages only when there's a genuine sub-domain requiring isolation. Pattern 4: Test File Organization Choose one approach and apply it consistently throughout the project. Option A: Colocated Tests Benefits: Tests live next to the code they verify. Easy to see coverage gaps. Option B: Parallel Test Directory Benefits: Clean separation between production and test code. Standard for larger projects. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills wshobson/python-project-structure