// 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.
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.
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`.
| name | polylith-base-creation |
| description | 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. |
💡 Terminology: this skill uses Polylith terms like brick, base, namespace, and theme. If they're unfamiliar, load
polylith-conceptsfirst.
uv run poly create base --name api
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 base is the entry point of a deployable application. For non-entry-point reusable code (business logic, capabilities), use
polylith-component-creationinstead.
| Option | Required | Default | Description |
|---|---|---|---|
--name | yes | — | Name of the base (also the package name). |
--description | no | "" | Optional human-readable description. |
bases/<namespace>/api/
├── __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/bases/<namespace>/api/test_core.py.
For the tdd theme layout (bases/api/{src,test}/<namespace>/api/...), load the polylith-workspace-setup skill.
# Minimal
uv run poly create base --name api
# With description
uv run poly create base --name consumer --description "Kafka order consumer"
core.py is empty boilerplate — there is no FastAPI/Typer/Lambda scaffolding. Fill it in manually after creation if asked.__init__.py is also empty. By Polylith convention it should re-export the brick's public symbols, so consumers import from <namespace>.api import … rather than reaching into core.py.polylith-sync and run poly sync, or run poly create project (the interactive prompt will offer to attach the base).loose and tdd themes — the CLI reads [tool.polylith.structure].theme from workspace.toml.After creation, verify the base exists using your file tools (e.g., check bases/<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.