Specx Project Structure
Create or reshape a Python FastAPI service repo into the specx clean core/delivery architecture using packaged scoped foundation bases. Use when starting an API backend, adding the first src package, or establishing `AGENTS.md`, `core/`, optional local `foundation/`, `delivery/`, infrastructure, `ioc/`, migrations, and tests.
Install
npx skills add maksimzayats/specx --skill specx-project-structuregit clone --depth 1 https://github.com/maksimzayats/specx.git /tmp/specx
mkdir -p ~/.claude/skills
cp -r /tmp/specx/.agents/skills/specx-project-structure ~/.claude/skills/specx-project-structurePersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# specx Project Structure Use this skill to create the repo shell and first runnable vertical slice. For details, read `references/blueprint.md`. ## Workflow 1. For a fresh framework-neutral repo, start with `specx init <path>`. It creates packaging, strict tooling, root `AGENTS.md`, a small `core/health` use case and pure service, `ioc/container.py`, and mirrored unit tests. It intentionally omits delivery and infrastructure; add those packages only with real technology-specific behavior. 2. Preserve an existing import package declared by the repo. For a new repo, derive a lowercase underscore name, normalize every non-identifier character, and verify `name.isidentifier()` and `not keyword.iskeyword(name)`; distribution names and import packages need not be identical. If normalization still yields a keyword or leading digit, choose an explicit valid package name rather than emitting it unchanged. 3. Create `src/<package>/` and `tests/` packages with empty `__init__.py` files only. 4. Add `specx` as a runtime dependency and import base classes from `specx.core.foundation`, `specx.delivery.foundation`, or `specx.infrastructure.foundation`. 5. Use `core/<scope>/` as the main boundary. Put application packages at the scope root: `capabilities/`, `dtos/`, `entities/`, `exceptions/`, `gateways/`, `repositories/`, `services/`, and `use_cases/`. Put scope-owned technical adapters under `infrastructure/` only when real IO exists.
Details
- Skill name
specx-project-structure- Repository
- maksimzayats/specx
- Path
.agents/skills/specx-project-structure/SKILL.md- License
- MIT
- Repo updated
- 8 August 2026
FAQ
What does the Specx Project Structure skill do?
Create or reshape a Python FastAPI service repo into the specx clean core/delivery architecture using packaged scoped foundation bases. Use when starting an API backend, adding the first src package, or establishing `AGENTS.md`, `core/`, optional local `foundation/`, `delivery/`, infrastructure, `ioc/`, migrations, and tests.
How do I install the Specx Project Structure skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add maksimzayats/specx --skill specx-project-structure. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Specx Project Structure popular?
It lives in maksimzayats/specx, which has 198 GitHub stars and 33 forks.
Related skills
Specx Add Core Service
198maksimzayats/specx
Add or refactor a specx core scope service. Use when implementing focused reusable business/application behavior under a core scope services package, extracting logic from a use case, injecting deterministic collaborators, accepting an active unit of work, choosing between Service and Capability, or keeping business decisions away from delivery and infrastructure.
Specx Add Core Use Case
198maksimzayats/specx
Add or refactor a specx core scope use case. Use when implementing an externally meaningful application action under a core scope use_cases package, adding same-file command/query inputs, result DTOs, coordinating services, opening a unit-of-work transaction, or moving behavior out of delivery or infrastructure into class-based application code.
Specx Add Delivery Controller
198maksimzayats/specx
Add delivery controllers for specx services, especially FastAPI HTTP routes. Use when creating top-level `delivery/` request/response schemas, one controller per scoped use-case set, route registration, FastAPI lifecycle managers, HTTP error translation, delivery-only auth/rate-limit/request services, or integration tests that exercise the delivery edge.
Specx Settings
198maksimzayats/specx
Add runtime configuration to specx Python services with `pydantic-settings`. Use when creating settings classes, environment variables, `.env.example`, injecting settings at delivery, infrastructure, or composition edges, documenting config, mapping configuration into typed core policy collaborators, or removing direct environment reads from core code.
Specx Foundation
198maksimzayats/specx
Use specx foundation bases in Python services, or add a tiny project-local `foundation/` base for missing categories or stateful framework bases.
Abi and Calling Conventions
293mohitmishra786/low-level-dev-skills
ABI and calling conventions skill for cross-language boundaries. Use when explaining System V AMD64, ARM AAPCS, RISC-V psABI, stack frames, variadic calls, or FFI register rules. Activates on queries about calling convention, ABI, System V AMD64, AAPCS, stack frame, variadic function, or FFI registers.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.