python-project-structure

Organizes Python projects with module architecture, public APIs, and directory layouts.

Updated Apr 23, 2026
One-click install
npx skills add https://github.com/SanketAdlak/PDMProjectDesign --skill python-project-structure-sanketadlak
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-project-structure
Source: https://github.com/SanketAdlak/PDMProjectDesign/tree/main/.agents/skills/python-project-structure
Command: npx skills add https://github.com/SanketAdlak/PDMProjectDesign --skill python-project-structure-sanketadlak

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Python codebases often grow into tangled collections of files with unclear boundaries, hidden dependencies, and inconsistent organization. This Skill provides concrete patterns for structuring projects so modules stay cohesive, public interfaces are explicit, and directory layouts remain navigable as the codebase scales. ## Core Features & Use Cases - Module Architecture Patterns: Apply one-concept-per-file organization, explicit __all__ public API definitions, and flat directory structures that avoid deep nesting. - Layout Strategies: Choose between layered architecture, domain-driven structure, colocated tests, or parallel test directories based on project needs. - Naming and Import Conventions: Enforce snake_case file naming, absolute imports, and consistent class-to-file name matching. - Use Case: When starting a new Python library, use this Skill to design the package layout with a clean __init__.py public interface, organized service and model modules, and a parallel tests directory. ## Quick Start Ask the AI to design a directory structure and module organization plan for your new Python project, including public API definitions with all.

Frequently Asked Questions about python-project-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a new Python project?

Use a src layout with your package containing focused modules grouped by concern, a parallel tests directory, pyproject.toml, and a README. Keep the hierarchy flat and add sub-packages only for genuine sub-domains.

How do I define a public API in a Python package?

Define __all__ in each module's __init__.py listing exactly which names are public. Import the public classes and functions there so consumers can import directly from the package, while unlisted members remain internal.

Should Python tests be colocated or in a separate directory?

Both approaches work if applied consistently. Colocated tests sit next to the code they verify and make coverage gaps visible, while a parallel tests directory cleanly separates production and test code, which is standard for larger projects.

When should I split a Python file into multiple modules?

Split a file when it handles multiple unrelated responsibilities, grows beyond roughly 300-500 lines depending on complexity, or contains classes that change for different reasons. Each file should focus on a single concept.

Should I use absolute or relative imports in Python?

Use absolute imports for clarity and reliability. Relative imports can break when modules are moved or reorganized, while absolute imports like 'from myproject.services import UserService' remain stable during refactoring.