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.
npx skills add wondelai/skills/clean-architecture --global 
Clean Architecture Robert C. Martin View on Amazon
02 What it is
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.
03 Key concepts
Five principles your agent applies.
Drawn from Clean Architecture — not advice it repeats back to you, but decisions it makes while it works.
04 Fit
When to use it, and
when not to.
four symptoms it fixes, and four it doesn't.
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!.
05 Prompts
Say it like this.
Name the skill at the end of a prompt and the agent applies the framework rather than a vibe. Or say nothing — it loads on its own when a task matches.
Restructure this application to follow Clean Architecture layers using clean-architecture skill
Identify Dependency Rule violations in this codebase using clean-architecture skill
Design use case and entity layers for this feature using clean-architecture skill
Decouple the database layer so we can swap ORMs without touching business logic using clean-architecture skill
06 About the author
07 Same stack
The stack it sits in.
Six Architecture & Systems skills. Most people run two: this one, and whichever fits the next problem.
All Architecture & Systems skills08 Questions
Before you install.
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!.
09 Guides that use it
Put it to work.
Long-form playbooks where this skill does part of the job.
One skill, one command.
Install Clean Architecture, or the whole stack.
npx skills add wondelai/skills/clean-architecture --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account