[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F1MD3VVZ89PP9MSDX5MZ75":3,"skill-same:01M7F1MD3VVZ89PP9MSDX5MZ75":46},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7F1MD3VVZ89PP9MSDX5MZ75","python-project-structure",null,"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.","shotcowboystyle\u002Fag-skills","shotcowboystyle","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F62471?v=4","01M7EZTCFCZJ6K3MYW8BPM4X6R","Curtis Blanton","01M7EZTCG1S5M04J90A931X9BX",0,"MIT","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fpython-development\u002Fskills\u002Fpython-project-structure\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: python-project-structure\ndescription: 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.\n---\n\n# Python Project Structure & Module Architecture\n\nDesign well-organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable.\n\n## When to Use This Skill\n\n- Starting a new Python project from scratch\n- Reorganizing an existing codebase for clarity\n- Defining module public APIs with `__all__`\n- Deciding between flat and nested directory structures\n- Determining test file placement strategies\n- Creating reusable library packages\n\n## Core Concepts\n\n### 1. Module Cohesion\n\nGroup related code that changes together. A module should have a single, clear purpose.\n\n### 2. Explicit Interfaces\n\nDefine what's public with `__all__`. Everything not listed is an internal implementation detail.\n\n### 3. Flat Hierarchies\n\nPrefer shallow directory structures. Add depth only for genuine sub-domains.\n\n### 4. Consistent Conventions\n\nApply naming and organization patterns uniformly across the project.\n\n## Quick Start\n\n```\nmyproject\u002F\n├── src\u002F\n│   └── myproject\u002F\n│       ├── __init__.py\n│       ├── services\u002F\n│       ├── models\u002F\n│       └── api\u002F\n├── tests\u002F\n├── pyproject.toml\n└── README.md\n```\n\n## Fundamental Patterns\n\n### Pattern 1: One Concept Per File\n\nEach file should focus on a single concept or closely related set of functions. Consider splitting when a file:\n\n- Handles multiple unrelated responsibilities\n- Grows beyond 300-500 lines (varies by complexity)\n- Contains classes that change for different reasons\n\n```python\n# Good: Focused files\n# user_service.py - User business logic\n# user_repository.py - User data access\n# user_models.py - User data structures\n\n# Avoid: Kitchen sink files\n# user.py - Contains service, repository, models, utilities...\n```\n\n### Pattern 2: Explicit Public APIs with `__all__`\n\nDefine the public interface for every module. Unlisted members are internal implementation details.\n\n```python\n# mypackage\u002Fservices\u002F__init__.py\nfrom .user_service import UserService\nfrom .order_service import OrderService\nfrom .exceptions import ServiceError, ValidationError\n\n__all__ = [\n    \"UserService\",\n    \"OrderService\",\n    \"ServiceError\",\n    \"ValidationError\",\n]\n\n# Internal helpers remain private by omission\n# from .internal_helpers import _validate_input  # Not exported\n```\n\n### Pattern 3: Flat Directory Structure\n\nPrefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult.\n\n```\n# Preferred: Flat structure\nproject\u002F\n├── api\u002F\n│   ├── routes.py\n│   └── middleware.py\n├── services\u002F\n│   ├── user_service.py\n│   └── order_service.py\n├── models\u002F\n│   ├── user.py\n│   └── order.py\n└── utils\u002F\n    └── validation.py\n\n# Avoid: Deep nesting\nproject\u002Fcore\u002Finternal\u002Fservices\u002Fimpl\u002Fuser\u002F\n```\n\nAdd sub-packages only when there's a genuine sub-domain requiring isolation.\n\n### Pattern 4: Test File Organization\n\nChoose one approach and apply it consistently throughout the project.\n\n**Option A: Colocated Tests**\n\n```\nsrc\u002F\n├── user_service.py\n├── test_user_service.py\n├── order_service.py\n└── test_order_service.py\n```\n\nBenefits: Tests live next to the code they verify. Easy to see coverage gaps.\n\n**Option B: Parallel Test Directory**\n\n```\nsrc\u002F\n├── services\u002F\n│   ├── user_service.py\n│   └── order_service.py\ntests\u002F\n├── services\u002F\n│   ├── test_user_service.py\n│   └── test_order_service.py\n```\n\nBenefits: Clean separation between production and test code. Standard for larger projects.\n\n## Advanced Patterns\n\n### Pattern 5: Package Initialization\n\nUse `__init__.py` to provide a clean public interface for package consumers.\n\n```python\n# mypackage\u002F__init__.py\n\"\"\"MyPackage - A library for doing useful things.\"\"\"\n\nfrom .core import MainClass, HelperClass\nfrom .exceptions import PackageError, ConfigError\nfrom .config import Settings\n\n__all__ = [\n    \"MainClass\",\n    \"HelperClass\",\n    \"PackageError\",\n    \"ConfigError\",\n    \"Settings\",\n]\n\n__version__ = \"1.0.0\"\n```\n\nConsumers can then import directly from the package:\n\n```python\nfrom mypackage import MainClass, Settings\n```\n\n### Pattern 6: Layered Architecture\n\nOrganize code by architectural layer for clear separation of concerns.\n\n```\nmyapp\u002F\n├── api\u002F           # HTTP handlers, request\u002Fresponse\n│   ├── routes\u002F\n│   └── middleware\u002F\n├── services\u002F      # Business logic\n├── repositories\u002F  # Data access\n├── models\u002F        # Domain entities\n├── schemas\u002F       # API schemas (Pydantic)\n└── config\u002F        # Configuration\n```\n\nEach layer should only depend on layers below it, never above.\n\n### Pattern 7: Domain-Driven Structure\n\nFor complex applications, organize by business domain rather than technical layer.\n\n```\necommerce\u002F\n├── users\u002F\n│   ├── models.py\n│   ├── services.py\n│   ├── repository.py\n│   └── api.py\n├── orders\u002F\n│   ├── models.py\n│   ├── services.py\n│   ├── repository.py\n│   └── api.py\n└── shared\u002F\n    ├── database.py\n    └── exceptions.py\n```\n\n## File and Module Naming\n\n### Conventions\n\n- Use `snake_case` for all file and module names: `user_repository.py`\n- Avoid abbreviations that obscure meaning: `user_repository.py` not `usr_repo.py`\n- Match class names to file names: `UserService` in `user_service.py`\n\n### Import Style\n\nUse absolute imports for clarity and reliability:\n\n```python\n# Preferred: Absolute imports\nfrom myproject.services import UserService\nfrom myproject.models import User\n\n# Avoid: Relative imports\nfrom ..services import UserService\nfrom . import models\n```\n\nRelative imports can break when modules are moved or reorganized.\n\n## Best Practices Summary\n\n1. **Keep files focused** - One concept per file, consider splitting at 300-500 lines (varies by complexity)\n2. **Define `__all__` explicitly** - Make public interfaces clear\n3. **Prefer flat structures** - Add depth only for genuine sub-domains\n4. **Use absolute imports** - More reliable and clearer\n5. **Be consistent** - Apply patterns uniformly across the project\n6. **Match names to content** - File names should describe their purpose\n7. **Separate concerns** - Keep layers distinct and dependencies flowing one direction\n8. **Document your structure** - Include a README explaining the organization\n","# Python Project Structure & Module Architecture\n\nDesign well-organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable.\n\n## When to Use This Skill\n\n- Starting a new Python project from scratch\n- Reorganizing an existing codebase for clarity\n- Defining module public APIs with `__all__`\n- Deciding between flat and nested directory structures\n- Determining test file placement strategies\n- Creating reusable library packages\n\n## Core Concepts\n\n### 1. Module Cohesion\n\nGroup related code that changes together. A module should have a single, clear purpose.\n\n### 2. Explicit Interfaces\n\nDefine what's public with `__all__`. Everything not listed is an internal implementation detail.\n\n### 3. Flat Hierarchies\n\nPrefer shallow directory structures. Add depth only for genuine sub-domains.\n\n### 4. Consistent Conventions\n\nApply naming and organization patterns uniformly across the project.\n\n## Quick Start\n\n```\nmyproject\u002F\n├── src\u002F\n│   └── myproject\u002F\n│       ├── __init__.py\n│       ├── services\u002F\n│       ├── models\u002F\n│       └── api\u002F\n├── tests\u002F\n├── pyproject.toml\n└── README.md\n```\n\n## Fundamental Patterns\n\n### Pattern 1: One Concept Per File\n\nEach file should focus on a single concept or closely related set of functions. Consider splitting when a file:\n\n- Handles multiple unrelated responsibilities\n- Grows beyond 300-500 lines (varies by complexity)\n- Contains classes that change for different reasons\n\n```python\n# Good: Focused files\n# user_service.py - User business logic\n# user_repository.py - User data access\n# user_models.py - User data structures\n\n# Avoid: Kitchen sink files\n# user.py - Contains service, repository, models, utilities...\n```\n\n### Pattern 2: Explicit Public APIs with `__all__`\n\nDefine the public interface for every module. Unlisted members are internal implementation details.\n\n```python\n# mypackage\u002Fservices\u002F__init__.py\nfrom .user_service import UserService\nfrom .order_service import OrderService\nfrom .exceptions import ServiceError, ValidationError\n\n__all__ = [\n    \"UserService\",\n    \"OrderService\",\n    \"ServiceError\",\n    \"ValidationError\",\n]\n\n# Internal helpers remain private by omission\n# from .internal_helpers import _validate_input  # Not exported\n```\n\n### Pattern 3: Flat Directory Structure\n\nPrefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult.\n\n```\n# Preferred: Flat structure\nproject\u002F\n├── api\u002F\n│   ├── routes.py\n│   └── middleware.py\n├── services\u002F\n│   ├── user_service.py\n│   └── order_service.py\n├── models\u002F\n│   ├── user.py\n│   └── order.py\n└── utils\u002F\n    └── validation.py\n\n# Avoid: Deep nesting\nproject\u002Fcore\u002Finternal\u002Fservices\u002Fimpl\u002Fuser\u002F\n```\n\nAdd sub-packages only when there's a genuine sub-domain requiring isolation.\n\n### Pattern 4: Test File Organization\n\nChoose one approach and apply it consistently throughout the project.\n\n**Option A: Colocated Tests**\n\n```\nsrc\u002F\n├── user_service.py\n├── test_user_service.py\n├── order_service.py\n└── test_order_service.py\n```\n\nBenefits: Tests live next to the code they verify. Easy to see coverage gaps.\n\n**Option B: Parallel Test Directory**\n\n```\nsrc\u002F\n├── services\u002F\n│   ├── user_service.py\n│   └── order_service.py\ntests\u002F\n├── services\u002F\n│   ├── test_user_service.py\n│   └── test_order_service.py\n```\n\nBenefits: Clean separation between production and test code. Standard for larger projects.\n\n## Advanced Patterns\n\n### Pattern 5: Package Initialization\n\nUse `__init__.py` to provide a clean public interface for package consumers.\n\n```python\n# mypackage\u002F__init__.py\n\"\"\"MyPackage - A library for doing useful things.\"\"\"\n\nfrom .core import MainClass, HelperClass\nfrom .exceptions import PackageError, ConfigError\nfrom .config import Settings\n\n__all__ = [\n    \"MainClass\",\n    \"HelperClass\",\n    \"PackageError\",\n    \"ConfigError\",\n    \"Settings\",\n]\n\n__version__ = \"1.0.0\"\n```\n\nConsumers can then import directly from the package:\n\n```python\nfrom mypackage import MainClass, Settings\n```\n\n### Pattern 6: Layered Architecture\n\nOrganize code by architectural layer for clear separation of concerns.\n\n```\nmyapp\u002F\n├── api\u002F           # HTTP handlers, request\u002Fresponse\n│   ├── routes\u002F\n│   └── middleware\u002F\n├── services\u002F      # Business logic\n├── repositories\u002F  # Data access\n├── models\u002F        # Domain entities\n├── schemas\u002F       # API schemas (Pydantic)\n└── config\u002F        # Configuration\n```\n\nEach layer should only depend on layers below it, never above.\n\n### Pattern 7: Domain-Driven Structure\n\nFor complex applications, organize by business domain rather than technical layer.\n\n```\necommerce\u002F\n├── users\u002F\n│   ├── models.py\n│   ├── services.py\n│   ├── repository.py\n│   └── api.py\n├── orders\u002F\n│   ├── models.py\n│   ├── services.py\n│   ├── repository.py\n│   └── api.py\n└── shared\u002F\n    ├── database.py\n    └── exceptions.py\n```\n\n## File and Module Naming\n\n### Conventions\n\n- Use `snake_case` for all file and module names: `user_repository.py`\n- Avoid abbreviations that obscure meaning: `user_repository.py` not `usr_repo.py`\n- Match class names to file names: `UserService` in `user_service.py`\n\n### Import Style\n\nUse absolute imports for clarity and reliability:\n\n```python\n# Preferred: Absolute imports\nfrom myproject.services import UserService\nfrom myproject.models import User\n\n# Avoid: Relative imports\nfrom ..services import UserService\nfrom . import models\n```\n\nRelative imports can break when modules are moved or reorganized.\n\n## Best Practices Summary\n\n1. **Keep files focused** - One concept per file, consider splitting at 300-500 lines (varies by complexity)\n2. **Define `__all__` explicitly** - Make public interfaces clear\n3. **Prefer flat structures** - Add depth only for genuine sub-domains\n4. **Use absolute imports** - More reliable and clearer\n5. **Be consistent** - Apply patterns uniformly across the project\n6. **Match names to content** - File names should describe their purpose\n7. **Separate concerns** - Keep layers distinct and dependencies flowing one direction\n8. **Document your structure** - Include a README explaining the organization\n",{"name":5,"description":7},"main","f846d9a97082ff30d613b55a085cef425d822473","plugins\u002Fpython-development\u002Fskills\u002Fpython-project-structure","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle","https:\u002F\u002Fshotcowboystyle.github.io","Building smarter with AI, automation & modern tools. Exploring how far one person can go without a big team using today’s AI.","2026-11-10 04:58:27",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add shotcowboystyle\u002Fag-skills --skill python-project-structure",{"tool":38,"command":39},"bunx","bunx skills add shotcowboystyle\u002Fag-skills --skill python-project-structure",{"tool":41,"command":42},"pnpm","pnpm dlx skills add shotcowboystyle\u002Fag-skills --skill python-project-structure","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fpython-development\u002Fskills\u002Fpython-project-structure\u002FSKILL.md",true,[],[47,53,60,67,74,81],{"skillNo":48,"name":49,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M7F1YRY5S5QRJ1V0BJS130QX","no-description","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fno-description\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7F1Y9BV2FJNQJ3NB32JS5CM","good-skill","Fixture skill that satisfies every rule.","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fgood-skill\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7F1XXBQ3NQRXZSS0KAGAR9V","broken-link","Links to a reference file that does not exist.","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fbroken-link\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7F1XBX4R46NR9W0HXQ7XCDX","Bad_Name","Name violates the kebab-case rule and does not match the directory.","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fbad-name\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7F1WNAF8WNEQ7S5HKT5VK0D","skill-authoring","Write, review, and validate portable agent skills in SKILL.md format. Use when creating a new skill, editing an existing one, or asked whether a skill follows the Agent Skills spec.","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Fskills\u002Fskill-authoring\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7F1W30TC0XFNSF7YBRGETK2","weigh-bags","Record scale readings for each bag — empty (tare), outbound, current, final — and reconcile them against the itemised inventory to find unaccounted weight. Use when the user gives a bag weight, says how heavy something is, weighs their luggage, or asks how close to the limit they are. Appends to bags.yaml and runs scripts\u002Freconcile.py.","https:\u002F\u002Fgithub.com\u002Fshotcowboystyle\u002Fag-skills\u002Fblob\u002Fmain\u002Fplugins\u002Ftravel-packing-assistant\u002Fskills\u002Fweigh-bags\u002FSKILL.md",[],[]]