Clean Architecture
Building maintainable, testable software architectures
Build maintainable software architectures using Robert C. Martin's Clean Architecture principles. This skill equips your AI agent with the Dependency Rule, layered architecture patterns, and boundary design that keeps business logic independent of frameworks and infrastructure.
Clean Architecture
npx skills add wondelai/skills/clean-architecture --global This skill is compatible with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other agentskills.io-compatible agents.
What is the Clean Architecture skill?
Clean Architecture is a free AI agent skill built on Robert C. Martin’s book. It enforces the Dependency Rule — source code dependencies point inward, from frameworks toward use cases toward entities — so your agent puts business logic where the database, the web framework and the vendor SDK can be swapped without touching it.
Key concepts from Clean Architecture your agent applies
The Dependency Rule
Dependencies point inward — outer layers depend on inner layers, never the reverse. Business rules know nothing about UI or databases.
Entities & Use Cases
Entities encapsulate enterprise-wide business rules. Use cases contain application-specific business rules that orchestrate entities.
Interface Adapters
Controllers, presenters, and gateways convert data between the format most convenient for use cases and the format used by external agencies.
Frameworks Are Details
Frameworks and databases are implementation details — keep them at the outer ring and make them replaceable.
SOLID Principles
Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion guide component design.
When to use Clean Architecture — and when not to
Reach for it when
- You cannot run a single business rule in a test without booting the web framework and a database first.
- Replacing the ORM or upgrading the framework would mean editing files all over the codebase, not just the edges.
- Nobody can say which layer a new class belongs in, so everything lands in one enormous services folder.
- You are deciding whether to split into microservices and want the boundaries drawn before the deployments are.
Reach for something else when
- The app is small and the layers would cost more than they save — Software Design’s complexity test is the better judge.
- You know you need boundaries but not where they go — Domain-Driven Design finds the seams the business actually has.
- The problem is naming, function length and readability inside one module — Clean Code is the more specific tool.
- You need the system to survive a failing dependency, not a cleaner layer diagram — that is Release It!.
Example prompts for the Clean Architecture skill
Restructure this application to follow Clean Architecture layers using clean-architecture skill
ArchitectureIdentify Dependency Rule violations in this codebase using clean-architecture skill
Architecture reviewDesign use case and entity layers for this feature using clean-architecture skill
DesignDecouple the database layer so we can swap ORMs without touching business logic using clean-architecture skill
RefactoringClean Architecture vs the other Architecture & Systems skills
All 6 Architecture & Systems skills are free and install the same way — the only question is which framework fits the job in front of you.
| Skill | Based on | Best for |
|---|---|---|
| Clean Architecture | Clean Architecture — Robert C. Martin | Building maintainable, testable software architectures |
| Domain-Driven Design | Domain-Driven Design — Eric Evans | Modeling complex business domains in software |
| Data-Intensive Apps | Designing Data-Intensive Applications — Martin Kleppmann | Designing reliable, scalable data systems |
| System Design | System Design Interview — Alex Xu | Scalable system design patterns and trade-offs |
| Release It! | Release It! — Michael T. Nygard | Production-ready software patterns for stability and resilience |
| High Perf Browser | High Performance Browser Networking — Ilya Grigorik | Browser networking performance optimization |
Frequently asked questions
How do I install the Clean Architecture skill?
Run npx skills add wondelai/skills/clean-architecture --global. It takes about 30 seconds and needs no account. The Clean Architecture skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.
Which book is the Clean Architecture skill based on?
It packages Clean Architecture by Robert C. Martin — co-author of the Agile Manifesto, creator of SOLID principles. The skill distils the book's method into instructions your agent follows while it works, covering the dependency rule, entities & use cases and interface adapters. It sits in the Architecture & Systems part of the library.
How is this different from the Domain-Driven Design skill?
Clean Architecture answers which way dependencies point across a boundary; Domain-Driven Design answers where the boundary belongs and what the things inside it mean. Martin’s rule tells you a repository interface lives in the inner circle and its Postgres implementation outside. Evans tells you it should be an OrderRepository, because Order is an aggregate root in your fulfilment context. Installed together, one supplies direction, the other supplies location and vocabulary.
What does the Dependency Rule actually say?
That source code dependencies may point only inward, toward higher-level policy. An inner circle must not name anything in an outer one — no class, no function, no variable, and especially no data format that an outer layer defines. Because control often has to flow outward at runtime, you invert it: the use case declares an interface, the outer layer implements it, and the source dependency still points in.
Isn’t Clean Architecture over-engineering for a small app?
Often, yes, and the skill will say so if you ask it to. Four concentric circles, an interface per gateway and a DTO at every crossing can easily cost more than they save on a CRUD app with one datastore. What survives at any size is the direction rule plus a real boundary at the one or two points of genuine volatility. Ask which boundaries earn their cost and treat the folder count as negotiable.
Does it cover microservices?
It covers the decision, not the operations. The book’s position, which the skill applies, is that services are units of deployment rather than units of architecture, and that services sharing one fat data model are a distributed monolith with network failures added. Expect it to push you toward a modular monolith with real internal boundaries, from which later extraction is mechanical. For capacity questions use System Design; for runtime failure modes, Release It!.
Guides that use this skill
How to Create a New App with AI Skills
Read guide Deep dive · EngineeringFrom Vibe-Coded Prototype to Production-Ready Product
Read guide Deep dive · EngineeringHow to Refactor a Codebase Buried in Technical Debt
Read guide Deep dive · ArchitectureHow to Design the Best Possible Architecture for a New App
Read guideInstall Clean Architecture
Free, open-source, and ready in 30 seconds.
npx skills add wondelai/skills/clean-architecture --global MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed
Don’t guess your AI engineering level.
Measure it.
AI Developer Scorecard
How production-grade is your AI engineering?
Twenty-five questions across the practices that separate vibe-coding from production-grade engineering. Instant score, per-section breakdown, and a 30/60/90-day playbook.
Score 0–75 · 30/60/90-day playbook Score yourself For CTOs & foundersCTO Scorecard
Is your engineering team ready for AI at scale?
Twenty-five questions on how your org adopts AI — adoption, governance, automation, and ROI. See where you sit on the path from Reactive to Strategic Leader.
Score 0–75 · Reactive → Strategic Leader Score your orgWe build the skills you already use. Now we’ll build yours.
Sprints from $3K · shipped to production, or you don’t pay the final milestone.