Adding Core Use Cases with specx: A Developer Dispatch

Where this fits

You've been asked to implement CreateInvoiceUseCase. You know it belongs in core/.../use_cases, but the project's specx conventions require a command input, a result DTO, a unit-of-work transaction, and service coordination. Instead of reading scattered examples, an agent with this skill can follow the same workflow a senior dev would: name the action, place it correctly, and write the class with all required same-file data classes.

Why agents benefit

• Agents can produce specx-consistent use cases from a single instruction, without guessing file locations or base classes.
• Same-file Command/Query and result DTO definitions reduce cross-module context loading and keep the agent's edits focused.
• The skill encodes ordering: read the reference first, then handle one action at a time, avoiding mixed refactors.
• It supports both greenfield additions and moving behavior out of delivery/infrastructure into class-based application code.
• Because inputs are explicit even when empty, agents learn to respect API boundaries instead of skipping them.

Practical scenarios

Adding a new application action

You need MarkInvoicePaidUseCase. The skill points the agent to core/invoicing/use_cases/mark_invoice_paid.py, defines a MarkInvoicePaidCommand, result DTO, and opens a unit-of-work transaction.

Refactoring service-layer logic

A fat delivery handler now contains payment logic. The agent extracts it into a core use case, keeping the handler thin and making the action unit-testable.

Wrapping an existing repository call in a query

A read-only dashboard endpoint needs a GetInvoiceSummaryQuery. The skill ensures the agent creates a query input and DTO even when the query takes no parameters.

Add it to your agent workflow

Install the skill with:

npx skills add maksimzayats/specx --skill specx-add-core-use-case

Then prompt an agent: "Use specx-add-core-use-case to add a CancelInvoiceUseCase in the invoicing scope." The agent will read the reference, place the file under core/invoicing/use_cases, and generate the command, DTO, and service wiring in the same pass. For a broader view of agent skills, see the skill's listing at OpenAgentSkill.

Compare before adopting

Treat this as a workflow accelerator, not a magic template. Compare quality signals: does the skill reference a maintained library (specx, 201 stars) and a clear reference doc? Check freshness by seeing if the author updates it for specx API changes. Also consider alternatives: a hand-written checklist or an existing in-house use-case template might fit better. Finally, evaluate workflow fit—does your team already use specx core scopes and unit-of-work patterns? If not, adopt only alongside that architecture.

Why it is worth tracking

The skill is tied to a focused, real-world convention: specx's BaseUseCase, BaseCommand, BaseQuery, and BaseDTO. That makes it easier to validate than broad "write clean architecture" prompts. With 201 stars and an active maintainer, it is likely to track specx changes. Re-evaluate when your specx version bumps or if you notice the generated code diverging from your codebase conventions.