python-project-structure Skill (wshobson): Project Layout

Gives Claude rules for laying out a Python project: one concept per file, explicit public APIs, flat folders and clear test placement.

Installs: 15.1K; on skills.sh
Stars: 42.1K; on GitHub
Updated: Oct 2026; last repo commit

python-project-structure makes Claude follow a small set of layout rules when you set up a Python project, reorganize modules or define public interfaces. The core rules are module cohesion, explicit interfaces with __all__, flat hierarchies and consistent conventions.

It bundles no scripts. The folder holds one SKILL.md with seven patterns, naming and import conventions, and a best-practices summary.

Good for

Developers starting a new Python project from scratch
Teams reorganizing a messy codebase
Library authors defining a public API with __all__

Install python-project-structure

Claude Code

Copy this prompt.

Install the python-project-structure skill in Claude Code. Run this command:

/plugin marketplace add wshobson/agents
/plugin install python-development@claude-code-workflows

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

The plugin route installs the whole python-development plugin: 16 skills, 3 agents and 1 command (counted from the repo tree). The skills-only routes install just this skill without the agents, commands or hooks, per the README. Pick one route, not both.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

When to Use This Skill
Core Concepts
1. Module Cohesion
2. Explicit Interfaces
3. Flat Hierarchies
4. Consistent Conventions
Quick Start
Fundamental Patterns
Pattern 1: One Concept Per File
Pattern 2: Explicit Public APIs with __all__
Pattern 3: Flat Directory Structure
Pattern 4: Test File Organization
Advanced Patterns
Pattern 5: Package Initialization
Pattern 6: Layered Architecture
Pattern 7: Domain-Driven Structure

Key facts

Author: wshobson (repo owner)
Repo: wshobson/agents
Installs on skills.sh: 15,083
Repo stars: 42,081
License: MIT
Last repo commit: 2026-10-30
Files in the skill folder: 1 file including SKILL.md

What it includes

Module cohesion, explicit interfaces, flat hierarchies, consistent conventions
The four ideas the other patterns build on.
Core Concepts
A src/ layout with services, models, api, tests and pyproject.toml
Shows the starting directory tree.
Quick Start
Split service, repository and models into separate files
Contrasts focused files with a kitchen-sink file.
Pattern 1: One Concept Per File
Decide what a package exports
Everything not listed stays private by omission.
Pattern 2: Explicit Public APIs with __all__
Prefer shallow folders
Add depth only for real sub-domains.
Pattern 3: Flat Directory Structure
Choose one test layout and keep it
Option A puts tests next to the code, Option B uses a parallel tests/ directory. It says to pick one and apply it consistently.
Pattern 4: Test File Organization
What goes in __init__.py
Uses __init__.py to give package consumers a clean public interface.
Pattern 5: Package Initialization
Keep layers apart
Each layer depends only on layers below it, never above.
Pattern 6: Layered Architecture
Organize by domain
Puts models, services, repository and api files inside each business domain folder, with a shared folder for common code.
Pattern 7: Domain-Driven Structure
Naming conventions and import style
Prefers absolute imports over relative ones.
File and Module Naming
Eight rules in one list
Includes splitting files at 300 to 500 lines and documenting your structure in a README.
Best Practices Summary

From the official docs

Questions

What does the python-project-structure skill do?

It gives Claude layout rules for Python projects. Claude applies them when you create a project, split a large module, define public APIs or decide where tests go.

Does it pick a framework or tool for me?

The SKILL.md covers file and folder organization, imports and naming. Its quick start tree includes a pyproject.toml, and its layered example mentions Pydantic schemas, but the text is about layout, not tool choice.

Does it say how long a file should be?

It suggests considering a split at 300 to 500 lines, and notes this varies by complexity.

How do I install it?

Use the install box above. The skill is a single SKILL.md file inside the wshobson/agents repo.

Is it safe to install?

It bundles no scripts. The folder holds one SKILL.md of written guidance. Claude may create or move files in your project when you ask it to reorganize, so check the plan first.

Does it use absolute or relative imports?

Absolute. Its import-style section lists absolute imports as preferred and relative imports as the pattern to avoid.

Information

updated Nov 2, 2026

Repository: wshobson/agents
Folder: plugins/python-development/skills/python-project-structure

wshobson/agents skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

wshobson/agents README · github.com
python-project-structure SKILL.md · github.com