Guide · Agent skill
How to use the Architecture Patterns agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The architecture-patterns skill gives an AI agent structured guidance on backend architecture, covering Clean Architecture, Hexagonal (ports and adapters) Architecture and Domain-Driven Design. This guide explains what the skill changes in the agent's behaviour, how to install it, how to ask for help in a way that triggers it, and what to check before relying on its output. By the end you will know how to get folder layouts, interface definitions and dependency rules proposed for a new service or refactor.
Architecture Patternswshobson/agents · MIT Download the skill Quick start
- 1Download the ZIP. Get the architecture-patterns skill ZIP from the download link on this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into .claude/skills/ in your project.
- 3Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill.
- 4Describe your architecture task. Name the service or module and the problem, such as a new microservice or a dependency cycle.
- 5Review the proposal. Check the suggested layers, ports and dependency rules against your existing codebase before applying them.
What the architecture-patterns skill makes the agent do
Agent skills are folders of instructions that an AI agent can load when a task matches them. This skill is focused on backend services. Once it is loaded, the agent follows the skill's guidance on keeping business rules separate from databases, web frameworks and external services.
In practice the agent can propose a folder layout, define the interfaces (ports) a use case depends on, set dependency rules between layers, and write unit tests that run without a real database. The skill also includes troubleshooting advice for problems such as circular imports and framework code leaking into domain entities.
- Clean Architecture: entities, use cases, interface adapters and frameworks, with dependencies pointing inward only
- Hexagonal Architecture: a framework-free domain core, ports, and adapters such as a PostgreSQL or Stripe adapter
- Domain-Driven Design: bounded contexts, context mapping, aggregates, value objects, repositories and domain events
Install the architecture-patterns skill
Download the ZIP for the skill from the download link on this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills. The skill's main instructions are in SKILL.md, with extra material in references/details.md and references/advanced-patterns.md, so keep those files together with it.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need a special command. The skill's description lists the situations it is meant for, so describe your task in those terms. Name the service or module, the problem and the layers you care about.
The skill is written for four kinds of task: designing clean architecture for a new microservice, refactoring a monolith toward bounded contexts, implementing hexagonal or onion architecture, and debugging dependency cycles between application layers.
- Design a Clean Architecture layout for a new order microservice in Python.
- Refactor this monolith into bounded contexts before we split out the billing service.
- Our use cases import the PostgreSQL adapter directly. Help me add ports so they can be tested in memory.
- I get ImportError between use_cases and adapters. Find the dependency cycle and suggest a fix.
Example: unit tests without a running database
One of the main goals of the skill is use-case tests that need no database, Docker or network. The skill's approach is to inject an in-memory implementation of the repository interface into the use case. The use case constructor accepts the abstract port, not the concrete class.
The skill's example defines an InMemoryUserRepository that stores users in a dictionary, then passes it to CreateUserUseCase in tests such as creating a user and rejecting a duplicate email.
- Keep database calls behind an IRepository-style interface
- Inject the in-memory implementation in tests
- Keep use cases importing only from domain/, never from adapters/ or infrastructure/
app/
├── domain/ # Entities, value objects, interfaces
├── use_cases/ # Application business rules
├── adapters/ # Concrete implementations
└── infrastructure/ # Framework wiring, config, DI containerSafety notes: scripts, network and requirements
The skill's listed requirements are none. It does not run scripts and does not use the network, according to its listing. It is a set of written guidance and reference files, so the agent's output is code and design proposals that you review and run yourself.
Because the patterns are generic, review every proposed layout and dependency rule against your own codebase and your team's existing architecture decisions before you apply them.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for getting useful results
Give the agent the real context: the language, the framework, the current folder structure and the bounded context names. The skill's advice is generic, so specifics produce better layouts.
For deeper work, ask about bounded context mapping, full multi-service project trees, Anti-Corruption Layers or Onion Architecture comparisons, which the skill covers in its advanced reference file.
- Share the existing folder tree and the names domain experts use
- Ask for value objects that validate invariants at construction time
- Ask for the smallest change first when refactoring a monolith
What people use it for
- Laying out the folders and ports for a new backend microservice before writing code
- Planning how to split a monolith into bounded contexts before extracting a service
- Making use-case tests run in memory by introducing repository interfaces
- Tracking down circular imports between use cases and adapters
Frequently asked questions
Is the architecture-patterns skill free to use?
The skill is published under the MIT licence, as listed on this page. Check the licence text in the source repository for the full terms before reuse.
What does the architecture-patterns skill require?
The listing shows no required tools, no scripts run by the skill, and no network use. You still need an agent environment that supports skills, such as the Claude apps or a Claude setup that reads skills folders.
How do I install an agent skill from a ZIP?
Unzip the downloaded file into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps, upload it under Settings → Capabilities → Skills.
Which architecture patterns does the skill cover?
It covers Clean Architecture, Hexagonal (ports and adapters) Architecture and Domain-Driven Design, including bounded contexts, aggregates, value objects, repositories and domain events. It also touches on Onion Architecture in its advanced reference.
How is this different from microservices-patterns or cqrs-implementation?
This skill focuses on structuring code inside a service: layers, ports and test boundaries. The related skills cover other concerns, such as decomposing a monolith into services, command and query separation, sagas and event stores.
Why does my agent keep importing database code into use cases?
The skill's troubleshooting says use cases must import only from domain/ and must depend on abstract ports. Ask the agent to move database calls behind an interface and inject an in-memory implementation in tests.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Backend developers designing a new service, or teams preparing to split a monolith into bounded contexts, will get clear layering rules and testable designs from this skill. Small scripts, prototypes and frontend or static projects are better off without these layers, and the patterns still need adapting to your team's existing decisions.
Download the skill