How to use the Python Project Structure agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can read and apply when a request matches the skill's description. This one is named python-project-structure and is described as covering Python project organization, module architecture, and public API design.

Once installed, the agent uses these guidelines when you set up a new project or organize modules. It can suggest a directory layout such as src/ with tests/ beside it, keep each file focused on one concept, define each package's public interface with __all__, prefer shallow folder structures, and use absolute imports.

• Suggests layouts such as a src/ package folder with tests/ next to it and a pyproject.toml and README.md at the top
• Recommends splitting files that handle several unrelated responsibilities or grow beyond roughly 300-500 lines
• Defines public APIs with __all__ and keeps unlisted names internal by convention
• Prefers flat folder structures and adds sub-packages only for genuine sub-domains
• Chooses between colocated tests and a parallel tests/ directory, applied consistently

How do you install the python-project-structure skill?

Download the skill ZIP from this page. Then choose one of the two install locations below. A personal skill is available across your projects, while a project skill applies only to the project that contains it.

Unzip the download into ~/.claude/skills/ for a personal install, or into your project's .claude/skills/ folder for a project install. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into the .claude/skills/ folder inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the skill with a natural request?

You do not need a special command. The agent decides to use a skill when your request matches its description, which mentions setting up new projects, organizing modules, defining public interfaces with __all__, and planning directory layouts. Describe what you are trying to do in plain language and mention the Python context.

If the agent does not seem to apply the guidance, name the topic directly, for example by asking it to follow the python-project-structure skill.

What are some example requests?

These examples match the situations listed in the skill's description. Adjust the details to your own project.

• Set up a new Python package for an internal billing library and suggest a directory layout.
• Reorganize this Python app, where services and models are tangled together, into clearer modules.
• Define __all__ for the public interface of my services package.
• Should my tests sit next to the code or in a parallel tests/ folder for this project?
• Plan the folder structure for a Python API with services, models and repositories.

What do you need before using it?

The skill lists no required tools, does not run scripts, and does not use the network. It is a set of written guidelines. You do need an AI agent setup that supports skills, and the skill is specific to Python, so it is only useful for Python code.

Because the guidance is opinionated, review suggested changes before applying them, especially in an existing codebase.

• No listed requirements
• Runs scripts: no
• Uses network: no
• Works only on Python projects

What should you check for safety and fit?

The skill itself does not execute code or contact the internet, so it has no scripting or network behaviour to audit. Its effect comes from the changes the agent proposes and makes in your files, so read those changes before accepting them.

It may conflict with a structure your team already uses. A large reorganization applied without review can be disruptive, so ask the agent for a plan first and move code in small steps.

• Ask for a plan before large file moves
• Keep changes in version control so you can revert them
• Check that renamed imports still work across the project

What tips help you get better results?

Give the agent context about your project's size, whether it is a library or an application, and any structure you want to keep. The skill's guidance is most useful when the agent knows the goal.

• Say whether you are building a library or an application, since the skill covers reusable library packages too
• Share your current folder tree when reorganizing
• State if you want to keep an existing layout, so the agent does not override it
• Ask for __all__ lists to be reviewed against what each module actually needs to export