ports-and-adapters — Claude Code skill: what it does, how to install
ports-and-adapters guides Claude Code in setting up Hexagonal Architecture in Symfony, isolating domain models from Doctrine, HTTP, and vendor SDKs.
MIT ★ 234 updated 2026-10-05
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-codeWhat ports-and-adapters does
This skill organizes Symfony code into Domain, Application, and Infrastructure layers. It models entities and value objects in plain PHP without ORM attributes. Ports sit in the domain as interfaces, while use cases rely on commands and handlers that talk solely to those ports.
Infrastructure handles adapters like Doctrine repositories and API clients, mapping entities externally with XML. Controllers stay in infrastructure, and service configurations bind ports to concrete adapters.
Applying these layers to a basic CRUD module without business logic adds pointless overhead. Domain tests run as plain unit tests without booting the Symfony kernel.
What it helps with
- isolate core domain logic from Symfony and Doctrine dependencies
- define port interfaces and bind them to infrastructure adapters
- configure XML entity mappings outside the domain layer
- write fast domain unit tests that avoid booting the framework kernel
Example prompts for the agent
- Structure the billing module into Domain, Application, and Infrastructure layers
- Define a repository port for customer accounts and set up its Doctrine adapter with XML mapping
- Implement an order placement use case using a command handler isolated from vendor SDKs
How to install ports-and-adapters
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-code2Manually: put the files in place
~/.claude/skills/ports-and-adapters/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ports-and-adapters/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a codex2Manually: put the files in place
.agents/skills/ports-and-adapters/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a cursor2Manually: put the files in place
.cursor/skills/ports-and-adapters/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dev-toolings/superpowers-symfony content/skills/ports-and-adapters2Manually: put the files in place
.github/skills/ports-and-adapters/SKILL.md1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a gemini-cli2Platform CLI
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/ports-and-adaptersManually: put the files in place
.devin/skills/ports-and-adapters/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ports-and-adapters
How to install ports-and-adapters in Claude Code?
Run npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-code in your terminal.
What does the ports-and-adapters skill do?
It enforces Hexagonal Architecture rules in Symfony projects, keeping src/Domain/ clean of framework imports.
How does it handle entity persistence without ORM attributes?
Entities stay free of Doctrine annotations or attributes, using external XML mappings inside the infrastructure layer instead.
Source text
SKILL.md · MIT
--- name: ports-and-adapters description: Implement Hexagonal Architecture (Ports and Adapters) in Symfony; separate domain logic from infrastructure with clear boundaries capabilities: [read, search] tags: [architecture] # projected by `bun run build` — do not edit by hand allowed-tools: - Read - Glob - Grep --- # Ports And Adapters (Symfony) ## Use when - Domain rules must not depend on Doctrine, HTTP, or a vendor SDK. - An infrastructure dependency (storage, payment, mail provider) must be swappable or faked. - Structuring a bounded context into Domain, Application and Infrastructure layers. ## Default workflow 1. Model the domain in plain PHP: entities and value objects without ORM attributes. 2. Declare ports as interfaces inside the domain, such as a repository interface. 3. Write use cases in the application layer as commands and handlers that depend only on ports. 4. Implement adapters in infrastructure (Doctrine repository, API client) and map entities outside the domain, with XML mapping. 5. Bind each port to its adapter in the service configuration; controllers live in infrastructure. ## Guardrails - Nothing under `src/Domain/` imports Symfony, Doctrine or vendor SDK classes. - Dependencies point inward: infrastructure knows the domain, never the reverse. - Do not add the layers to a CRUD module with no business rules. - Test the domain with plain unit tests and the adapters with integration tests. ## Progressive disclosure - Use this file for execution posture and risk controls. - Open references when deep implementation details are needed. ## Output contract - The layer layout and the port interfaces. - The adapters and their service bindings. - Domain unit tests that boot no kernel. ## References - `reference.md`
© dev-toolings · MIT · dev-toolings/superpowers-symfony