python-project-structure

Overview of python-project-structure skill

The python-project-structure skill helps you design a Python codebase that stays understandable as it grows. It is best for developers who are starting a new package, cleaning up a messy repository, or deciding how modules, packages, tests, and public imports should be organized before entropy sets in.

What the python-project-structure skill actually does

This skill focuses on project setup decisions that affect long-term maintainability: module boundaries, package depth, directory layout, and explicit public APIs using __all__. It is not a scaffolding generator or framework-specific starter. Its value is in helping you make better structural decisions early.

Best fit for readers and teams

Use python-project-structure if you are:

• creating a reusable library or internal package
• splitting a growing app into clearer modules
• unsure whether to use flat or nested packages
• standardizing how code is exposed from package entry points
• trying to make imports and ownership more predictable

It is especially useful for teams that want structure guidance without adopting a heavy architecture framework.

Real job-to-be-done

Most users are not looking for theory; they want to answer practical questions like:

• Where should business logic live?
• When should I create a subpackage?
• Should tests mirror the source tree?
• What belongs in __init__.py?
• How do I expose a clean public API without leaking internals?

The python-project-structure skill is most helpful when you bring those decisions into the prompt directly.

What differentiates this skill from a generic prompt

The repository guidance is opinionated in a useful way:

• prefer cohesive modules over grab-bag files
• keep hierarchies shallow unless real sub-domains exist
• make public interfaces explicit
• use consistency as a design tool, not an afterthought

That makes it stronger than a vague “organize my Python project” prompt, especially for python-project-structure for Project Setup where small layout choices compound later.

What it does not cover deeply

This skill is narrow by design. It does not primarily solve:

• dependency management
• deployment layout
• framework-specific conventions
• build backends and packaging edge cases
• monorepo tooling strategy

If your main problem is Django, FastAPI, Poetry, Hatch, or CI configuration, use this skill for structure decisions, then pair it with a more specific setup skill or prompt.

How to Use python-project-structure skill

Install context for python-project-structure

The upstream SKILL.md does not include an install command, so directory users typically add it from the containing repository with a command like:

npx skills add https://github.com/wshobson/agents --skill python-project-structure

If your environment uses a different skill loader, the important part is the skill path from wshobson/agents under plugins/python-development/skills/python-project-structure.

Read this file first

Start with:

• SKILL.md

This skill has no extra README.md, metadata.json, resources/, or helper scripts in the folder, so almost all useful guidance is in that single file. That is good for fast adoption, but it also means you should read it fully before relying on assumptions.

What input the skill needs

The python-project-structure install step is easy; the harder part is supplying enough context for a good structure recommendation. Give it:

• project type: library, CLI, service, automation tool, data package
• current or planned top-level features
• expected growth areas
• desired public API surface
• testing approach
• whether this is greenfield or a refactor
• any framework or packaging constraints

Without that, the output will drift toward generic layouts.

Turn a rough goal into a usable prompt

Weak prompt:

• “Organize my Python project.”

Stronger prompt:

• “Use the python-project-structure skill to propose a package layout for a Python library that parses invoices, normalizes fields, and exports to multiple formats. I want a clean public API for downstream users, shallow package depth, and tests separated from source. Show recommended directories, what belongs in each module, and what to expose from __init__.py.”

Why this works:

• it names the domain
• it reveals likely sub-domains
• it states API goals
• it constrains package depth
• it gives the skill something to optimize

Ask for decisions, not just a tree

The best python-project-structure usage is not “draw me folders.” Ask the skill to justify:

• why a module exists
• what changes together
• which imports are public
• what stays internal
• when to split a file into a package

That pushes the output from cosmetic organization into maintainable architecture.

Suggested workflow for project setup

A practical workflow:

1. Describe the project’s main capabilities and users.
2. Ask for a first-pass directory layout.
3. Ask the skill to identify module boundaries by cohesion.
4. Ask for package-level public API recommendations using __all__.
5. Review where tests should live and how they map to source.
6. Stress-test the layout with one or two future features.
7. Only then create files and imports.

This sequence fits python-project-structure for Project Setup better than starting from a copied template.

Use the skill for refactors, not only new repos

You can also use python-project-structure guide prompts on an existing codebase. Provide:

• current tree
• pain points like circular imports or giant modules
• examples of confusing imports
• modules that change too often together

Then ask for a target structure and a staged migration plan. This is much more actionable than asking for “best practices.”

Repository concepts to pay attention to

The source emphasizes a few design principles that should shape your prompt:

• one concept per file
• explicit public interfaces
• flat hierarchies by default
• consistent naming and organization

When your prompt conflicts with those principles, say why. For example, if you need deeper nesting for domain separation, state the domain boundaries up front.

Example prompt for a library package

“Apply the python-project-structure skill to a Python library with three concerns: input parsing, validation, and export. Propose a src/ layout, recommend which modules should be packages versus single files, define the public imports for package consumers, and explain where internal helpers should live. Keep the hierarchy shallow unless there is a strong domain reason.”

Example prompt for an app or service

“Use python-project-structure to reorganize a Python service that currently has utils.py, helpers.py, and models.py doing too many unrelated things. Suggest a cleaner module split based on cohesion, test placement, and a directory structure that stays readable for a 5-person team.”

Practical adoption tips that improve output quality

To get better results:

• include a rough file tree if one already exists
• name the imports you want users to write
• mention whether backward compatibility matters
• say if you prefer src/ layout
• ask the model to flag over-nesting and “misc” modules

Those details materially improve recommendations because they reveal constraints the skill itself cannot infer.

python-project-structure skill FAQ

Is python-project-structure good for beginners?

Yes, if you already know basic Python files and imports. The skill is readable and practical, but it assumes you can evaluate tradeoffs like package depth and public API exposure. Beginners will get more value if they use it on a small real project rather than abstract examples.

When is python-project-structure worth installing?

Install it when structure decisions are recurring or expensive to revisit later. If you are building anything beyond a throwaway script, python-project-structure can help you avoid vague module names, unstable imports, and overgrown files.

How is this different from asking an AI for a folder tree?

A generic prompt often produces a plausible tree with weak reasoning. The python-project-structure skill adds a clearer lens: cohesion, explicit interfaces, and shallow hierarchies. That usually leads to better package boundaries and fewer decorative folders.

Does it generate a full project scaffold?

No. It is guidance, not a code generator. Expect recommendations, patterns, and examples rather than a framework-ready starter repo.

Is python-project-structure only for libraries?

No. It is strongest for libraries and reusable packages because public API design is central, but it also helps with services and applications that need clearer internal boundaries.

When should I not use python-project-structure?

Skip it if your main need is:

• framework conventions already dictated elsewhere
• one-off scripts with no growth path
• deployment and packaging automation rather than code organization
• repo bootstrap commands and templates

In those cases, this skill may be too architectural and not operational enough.

Does it cover test layout decisions?

Yes, at a strategic level. It helps you think about test placement and tree shape, but it does not replace deeper testing guidance on fixtures, tooling, or CI.

How to Improve python-project-structure skill

Give python-project-structure concrete domain boundaries

The biggest quality jump comes from naming the real sub-domains in your project. “Payments, invoices, reconciliation” produces better module boundaries than “backend logic.” The skill can only separate concepts that you articulate.

Show intended imports and public API goals

If consumers should write imports like from mypkg import Client, say so. Public API expectations help the skill recommend __init__.py exports, package boundaries, and which modules should stay internal.

Include current pain points in refactor prompts

For an existing repo, mention issues such as:

• circular imports
• giant utils.py
• duplicate validation logic
• unstable internal imports across modules
• unclear ownership of models versus services

This helps the python-project-structure skill optimize for your real bottleneck instead of idealized cleanliness.

Ask for tradeoffs, not one answer

A strong improvement prompt is:

• “Give me two layout options: one optimized for simplicity now, one optimized for future domain growth.”

That is often better than requesting a single “best” structure, especially early in project setup.

Validate the first proposal against future changes

After the first output, ask:

• what happens if I add plugins?
• what if I split sync and async clients?
• where would shared schemas live?
• which module is most likely to become overcrowded?

This second-pass pressure test is where python-project-structure usage becomes genuinely useful.

Common failure modes to watch for

Poor outputs usually include:

• folders created without a real responsibility
• deep nesting for cosmetic grouping
• public APIs that leak internals
• catch-all files like common.py or helpers.py
• splitting code too early before stable concepts exist

If you see those patterns, ask the model to simplify and justify every package boundary.

Improve prompts with a mini spec

A compact input format works well:

• Project type:
• Main features:
• External users of the package:
• Expected growth areas:
• Preferred imports:
• Existing pain points:
• Constraints:

This gives the skill enough context without turning the prompt into a long design document.

Iterate from structure to files to exports

Do not ask for everything at once. A better sequence is:

1. directory layout
2. file responsibilities
3. package exports
4. import examples
5. migration steps

That staged approach reduces vague recommendations and makes python-project-structure guide outputs easier to adopt.

Improve the skill’s output with repository reality

Before accepting a recommendation, compare it with:

• actual team ownership
• current import paths
• release compatibility needs
• packaging expectations in pyproject.toml

The skill is strongest as a decision aid. It still needs your repository’s operational reality to produce a structure you can keep.