Source: wshobson/agents · Maintainer: community: Seth Hobson · License: MIT · Checked: 24 October 2026
What is the architecture patterns skill?
The architecture-patterns skill teaches a coding agent three backend structures: Clean Architecture, hexagonal architecture (ports and adapters) and Domain-Driven Design. It is for developers who want an agent to lay out a new service, or untangle an old one, with clear dependency rules and use cases you can test without a database.
It is part of the backend-development plugin in wshobson/agents, Seth Hobson's catalog of plugins, agents and skills for Claude Code, Codex, Cursor and other tools. The skill's description reads: "Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use this skill when designing clean architecture for a new microservice, when refactoring a monolith to use bounded contexts, when implementing hexagonal or onion architecture patterns, or when debugging dependency cycles between application layers."
As of 24 October 2026, its skills.sh page listed 24.1K installs (snapshot, 24 October 2026).
What does it do?
The agent loads the skill on its own when a task matches the description: a new microservice, a monolith being split into bounded contexts, a hexagonal or onion layout, or an import cycle between layers. The SKILL.md states its contract plainly. Given "a service boundary or module to architect," it produces a "layered structure with clear dependency rules, interface definitions, and test boundaries."
What the SKILL.md covers:
- Clean Architecture. Four layers (entities, use cases, interface adapters, frameworks and drivers) with dependencies pointing inward only.
- Hexagonal architecture. A framework-free domain core, ports as abstract interfaces, and adapters such as a PostgreSQL, Stripe or REST adapter.
- Domain-Driven Design. Strategic patterns (bounded contexts, context mapping, ubiquitous language) and tactical ones (entities, value objects, aggregates, repositories, domain events).
- Testing with in-memory adapters. A full Python example that tests a
CreateUserUseCaseagainst an in-memory repository, with no database, Docker or network. - Troubleshooting. Six named problems with fixes, covered below.
The folder has two reference files the agent opens when the summary isn't enough:
| File | What it holds |
|---|---|
references/details.md |
A Clean Architecture directory tree and code for an entity, a repository interface, a use case, a PostgreSQL repository and a FastAPI controller, plus a hexagonal example with a Stripe payment adapter |
references/advanced-patterns.md |
A multi-service project tree, onion versus Clean Architecture, an anti-corruption layer with an HTTP client, a context map, and dependency injection wiring |
The skill ends by pointing to related skills in the same plugin: microservices-patterns, cqrs-implementation, saga-orchestration and event-store-design.
How do you install it?
The repo README documents several install routes, including these. Use one per tool so the skill isn't loaded twice.
Just this skill. This is the command shown on skills.sh, using the skills CLI:
npx skills add https://github.com/wshobson/agents --skill architecture-patterns
Or with GitHub CLI 2.90 or later, as the README lists:
gh skill install wshobson/agents architecture-patterns
Both copy only the skill folder, under its bare name. For Claude Code that is .claude/skills/architecture-patterns/ in a project or ~/.claude/skills/architecture-patterns/ for every project, the locations in the Claude Code skills docs. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
The backend-development plugin in Claude Code. Inside a session:
/plugin marketplace add wshobson/agents
/plugin install backend-development@claude-code-workflows
That adds all nine skills in the plugin, including api-design-principles, plus agents such as backend-architect and event-sourcing-architect. Plugin skills are namespaced, so this one runs as /backend-development:architecture-patterns.
Codex plugin. From the README:
codex plugin marketplace add wshobson/agents
codex plugin add backend-development@claude-code-workflows
claude.ai. The MIT License permits copies, so you can zip the folder and upload it under Customize > Skills, following Anthropic's skills help article.
How do you use it?
Name the boundary you want structured and the pain you're trying to fix. The skill works best when it can see the code it's restructuring.
Example prompts (suggestions, not quotes from the repo):
Lay out a new billing service with Clean Architecture: entities, use cases, adapters. Show the directory tree and the repository interface first.Our Django views call the ORM directly. Refactor the signup flow into a use case with a repository port and an in-memory adapter for tests.We get ImportError between use_cases and adapters. Find the cycle and fix it using the skill's dependency rule.Split this monolith into bounded contexts. Propose the contexts, a context map and where an anti-corruption layer is needed.Make Email and Money value objects that validate in the constructor, and update the Order aggregate to use them.
Requirements: nothing to install beyond the skill. The examples assume Python with dataclasses and abc; the reference code also uses FastAPI, asyncpg and httpx, which you'd need only if you keep that stack.
What do the troubleshooting rules say?
This section maps symptoms to fixes:
- Use case tests need a running database. Business logic leaked into infrastructure; move database calls behind a repository interface and inject an in-memory version in tests.
- Circular imports between layers.
use_cases/must import only fromdomain/, never fromadapters/orinfrastructure/. - Framework decorators on domain entities. Keep SQLAlchemy or Pydantic annotations on a separate ORM model and map to the entity in the repository.
- Logic piling up in controllers. A controller should parse the request, call a use case and map the response.
- Value objects failing too late. Validate in
__post_init__or the constructor so an invalid value can't be created. - Context bleed. If one bounded context imports another's entities, add an anti-corruption layer and a local ID value object.
Tips and limits
- It assumes full layering. The SKILL.md says every layer boundary is crossed via an abstract interface. If that is more structure than your service needs, tell the agent where to stop.
- Python examples only. Ask explicitly for another language and the agent will translate, but the reference code is Python.
- No scripts. The skill runs nothing and writes no files by itself.
- Security audits. On 24 October 2026 the skills.sh page showed Pass from Gen Agent Trust Hub, Socket and Snyk.
- License. MIT, per the repo's LICENSE (copyright 2024 Seth Hobson). Keep the notice if you copy or change it.
Save it in your Kipt library
Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own. Open Skills, paste this skill's GitHub folder link into the import box, and Kipt brings in the SKILL.md and both reference files. Then install every skill in your library into Claude Code or Codex with npx skills add https://github.com/<you>/<repo>.git --all -g. Kipt is not affiliated with Seth Hobson or wshobson/agents.
Similar skills
- Improve codebase architecture skill: finds shallow modules in an existing codebase and proposes deepening refactors.
- Domain modeling skill: builds the shared glossary and ADRs that DDD's ubiquitous language depends on.
- API design principles skill: the sibling skill for the HTTP layer on top of your use cases.
- TDD skill: test-first loops at agreed seams, which pair well with in-memory adapters.