// Create a Polylith component with `poly create component` — a reusable, isolated brick implementing business logic, a feature, a domain module, or a capability. Use when adding non-entry-point code that bases or other components will import.
| name | polylith-component-creation |
| description | Create a Polylith component with `poly create component` — a reusable, isolated brick implementing business logic, a feature, a domain module, or a capability. Use when adding non-entry-point code that bases or other components will import. |
💡 Terminology: this skill uses Polylith terms like brick, component, namespace, and theme. If they're unfamiliar, load
polylith-conceptsfirst.
uv run poly create component --name user_service
Command prefix: If you do not know the package manager, list lock files with ls uv.lock poetry.lock pdm.lock 2>/dev/null (a pyproject.toml is always present, so it tells you nothing on its own). Use uv run poly (uv), poetry poly (poetry), pdm run poly (pdm), hatch run poly (hatch), or poly (activated venv). Examples below use uv run.
A component is reusable, non-entry-point code (business logic, domain features, capabilities). For entry points (HTTP API, CLI, Lambda handler), use
polylith-base-creationinstead.
| Option | Required | Default | Description |
|---|---|---|---|
--name | yes | — | Name of the component (also the package name). |
--description | no | "" | Optional human-readable description. |
components/<namespace>/user_service/
├── __init__.py # Public interface — empty; add re-exports here
└── core.py # Implementation — empty; user fills it in
If [tool.polylith.test].enabled = true in workspace.toml, the CLI also creates test/components/<namespace>/user_service/test_core.py.
For the tdd theme layout (components/user_service/{src,test}/<namespace>/user_service/...), load polylith-workspace-setup.
# Minimal
uv run poly create component --name user_service
# With description
uv run poly create component --name greeting --description "Greeting domain"
core.py and __init__.py are empty boilerplate. The component is not "ready" — the user fills in core.py, then re-exports its public API from __init__.py:
# components/<namespace>/user_service/__init__.py
from <namespace>.user_service.core import create_user, get_user
from <namespace>.user_service import create_user), never via core.py directly. poly deps --interface (load polylith-dependency-visualization) flags violations.poly sync (load polylith-sync).After creation, verify the component exists using your file tools (e.g., check components/<namespace>/<name>/__init__.py). Then, you will likely need to populate core.py and __init__.py using your file writing tools since they are created empty.
Create a Polylith base with `poly create base` — the entry point of a deployable application (HTTP API, CLI, message-queue consumer, AWS Lambda handler, GCP Cloud Function, scheduled job). Use when the user wants to add a service, API, endpoint, handler, or any new entry point to a Polylith workspace.
Safely remove a Polylith brick (component or base) from the workspace. Use when the user wants to delete, remove, or tear down a component or base.
Validate a Polylith workspace with `poly check` — the canonical CI gate. Verifies brick imports against project `pyproject.toml`s, third-party library declarations vs. the lock file, and (under `--strict`) cross-project version consistency. Exits 1 on failure. Use when the user wants to lint, validate, verify, or CI-gate a Polylith workspace.
Provides foundational knowledge about Polylith architecture, including the glossary (bases, components, projects, workspaces), theme layouts, and package manager mapping. Use this when you need to understand Polylith terminology or how the repository is structured conceptually before taking action.
Add or manage third-party dependencies in a Polylith workspace. Use when the user wants to install a new library (e.g., requests, fastapi) for a brick or project.
Visualize **brick × brick** dependencies with `poly deps` — find circular dependencies, inspect a brick's public interface, and detect interface-bypass violations. Use for "what depends on what", "circular deps", "interface violation". For brick × project usage, use `polylith-workspace-inspection`.