Adding specx Infrastructure Adapters Without the Guesswork

Where this fits

You have just defined a core scope in specx. The domain model is clean, but now you need Postgres persistence, Alembic migrations, Redis caching, and an OpenAI gateway. Your agent starts writing infrastructure code by hand, and there is no clear boundary between owned repositories and external business gateways. This skill turns that moment into a repeatable process: it tells the agent to read references/adapter.md first, then implement adapters under core/<scope>/infrastructure/<technology>/, and bind them through diwire so ports are explicit.

Why agents benefit

• Distinguishes repository ports (owned persistence, inherit BaseRepository) from gateway ports (external capabilities, inherit BaseGateway), so the agent does not misuse one for the other.
• Places concrete implementations in core/<scope>/infrastructure/<technology>/, preserving the core scope and making swappable infrastructure visible.
• Requires @abstractmethod on port methods and external-effect declarations on gateways, giving agents a checkable contract before writing SQLAlchemy or HTTP client code.
• Provides a consistent workflow for Alembic-backed SQLAlchemy repositories, Redis stores, unit-of-work implementations, file/queue adapters, and OpenAI SDK gateways.
• Makes dependency wiring explicit with diwire bindings, which helps agents inject sessions, clients, and connections without hiding them inside domain code.

Practical scenarios

Adding PostgreSQL repositories with Alembic migrations

You need persistence for Order in the orders scope. The agent reads the adapter reference, creates a repository port under repositories/, implements it with SQLAlchemy under infrastructure/postgres/, and adds an Alembic migration. diwire binds the port to the concrete repository.

Wiring an OpenAI gateway for a chat scope

The chat domain should not import the OpenAI SDK. The agent defines a gateway port that declares the external effect, implements it under infrastructure/openai/, and injects the client through diwire. Core code stays SDK-free and testable.

Introducing Redis stores and a unit of work

You want caching and transactional consistency between a repository and an outbound event queue. The skill guides the agent to implement a Redis store for cache reads, a unit of work that coordinates repository changes, and a queue adapter that publishes domain events after commit.

Add it to your agent workflow

Install the skill:

npx skills add maksimzayats/specx --skill specx-add-infrastructure-adapter

Then ask your agent:

Use the specx-add-infrastructure-adapter skill to add a SQLAlchemy repository and Alembic migration for the User aggregate in the identity scope, then bind it with diwire.

The agent reads references/adapter.md, follows the four-step workflow, and produces infrastructure code that matches the core ports.

Compare before adopting

Check repository and migration freshness: is specx actively maintained, and does the adapter guidance match your SQLAlchemy/Alembic version? Look for alternative ways to generate adapters, but weigh them against this skill's explicit repository/gateway split. Finally, confirm it fits your workflow: if you do not use diwire or specx scope conventions, you may need to adapt its output.

Why it is worth tracking

With 201 GitHub stars and a focused research-oriented author, specx-add-infrastructure-adapter is a signal that agent-friendly infrastructure generation is moving beyond generic code templates. The skill documents a specific, opinionated workflow rather than a loose collection of prompts, which makes it easier to evaluate and adopt. You can find the skill details at https://www.openagentskill.com/skills/maksimzayats-specx-add-infrastructure-adapter. If you build specx-based systems or want your agent to handle adapter code with consistent boundaries, it is worth evaluating now.