Clean Architecture Skills

A collection of skills for AI coding agents that provide code review, architecture guidance, and refactoring suggestions based on Clean Architecture and Kent Beck's simple design philosophy.

Designed primarily for Claude Code, with support for other AI coding assistants that use local skill directories.

What's Included

Clean Architecture

Reviews and guides code using Robert C. Martin's Clean Architecture principles.

• Dependency Rule — Detect dependencies that point in the wrong direction
• Layer Boundaries — Review Entities, Use Cases, Interface Adapters, and Infrastructure
• Dependency Inversion — Guide communication across architectural boundaries
• SOLID Principles — Review SRP, OCP, LSP, ISP, and DIP
• Architecture Design — Help design new features without coupling business rules to frameworks

Kent Beck Style

Reviews code using Kent Beck's refactoring philosophy and simple design principles.

• Code Smells — Detect structural and readability problems
• Refactoring — Suggest small, behavior-preserving improvements
• Simple Design — Apply YAGNI, KISS, and the 4 Rules of Simple Design
• Intention-Revealing Code — Improve naming and make code easier to understand
• Incremental Improvement — Prefer small, safe changes over large rewrites

Installation

Claude Code

Add this repository as a plugin marketplace:

/plugin marketplace add nathankim0/clean-architecture-skills

Then install the skills you want.

Clean Architecture

/plugin install clean-architecture@clean-architecture-skills

Kent Beck Style

/plugin install kent-beck-style@clean-architecture-skills

You can install either skill independently or use both together.

Manual Installation

Clone the repository:

git clone https://github.com/nathankim0/clean-architecture-skills.git

Then copy the desired skill into the skill directory used by your AI coding assistant.

Other AI Assistants

Usage

The skills are designed to work naturally from regular prompts.

Review an Entire Project

Review this project using clean architecture principles.

Review a Specific Module

Check the dependencies in src/domain and identify any clean architecture violations.

Design a New Feature

Design user authentication using clean architecture.

Review Code Smells

Review this code for code smells and suggest refactorings.

Refactor Existing Code

Help me refactor this long method using Kent Beck's approach.

Review for Simplicity

Check whether this implementation follows YAGNI and KISS.

Improve Naming

Improve the naming and readability of this module.

Use Both Skills Together

Review this feature for clean architecture violations, then suggest small refactorings to simplify the implementation.

Clean Architecture

The Dependency Rule

The central rule of Clean Architecture is:

Source code dependencies must point inward, toward higher-level policies.

┌─────────────────────────────────────────────────────────┐
│                  Frameworks & Drivers                   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Interface Adapters                 │    │
│  │                                                 │    │
│  │  ┌─────────────────────────────────────────┐    │    │
│  │  │                Use Cases                │    │    │
│  │  │                                         │    │    │
│  │  │  ┌─────────────────────────────────┐    │    │    │
│  │  │  │            Entities             │    │    │    │
│  │  │  │                                 │    │    │    │
│  │  │  │   Enterprise Business Rules     │    │    │    │
│  │  │  └─────────────────────────────────┘    │    │    │
│  │  └─────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

                     Dependencies flow inward →

Business rules should not depend on databases, frameworks, UI libraries, or external APIs.

Instead, implementation details depend on abstractions defined closer to the business rules.

Layer Responsibilities

SOLID Principles

Kent Beck Style

The Kent Beck skill focuses less on introducing architecture and more on making existing code simpler, clearer, and easier to change.

Simple Design

Prefer code that:

1. Passes the tests
2. Reveals intention
3. Avoids duplication
4. Has the fewest unnecessary elements

The skill also applies principles such as:

• YAGNI — Don't build functionality before it is needed
• KISS — Prefer the simplest design that solves the current problem
• Small Steps — Refactor incrementally
• Behavior Preservation — Improve structure without changing behavior
• Intention-Revealing Names — Make the code explain itself

Code Smells

The skill can identify common categories of code smells, including:

• Bloaters
• Object-Orientation Abusers
• Change Preventers
• Dispensables
• Couplers

It then recommends targeted refactorings instead of broad rewrites.

Example Project Structure

A typical Clean Architecture project might look like this:

src/
├── domain/                         # Entities
│   ├── entities/
│   │   ├── User.ts
│   │   └── Order.ts
│   └── value-objects/
│       └── Email.ts
│
├── application/                    # Use Cases
│   ├── use-cases/
│   │   ├── CreateOrderUseCase.ts
│   │   └── GetUserUseCase.ts
│   └── ports/
│       ├── input/
│       │   └── CreateOrderInput.ts
│       └── output/
│           └── UserRepository.ts
│
├── adapters/                       # Interface Adapters
│   ├── controllers/
│   │   └── OrderController.ts
│   ├── presenters/
│   │   └── UserPresenter.ts
│   └── gateways/
│       └── UserRepositoryImpl.ts
│
└── infrastructure/                 # Frameworks & Drivers
    ├── database/
    │   └── PostgresConnection.ts
    ├── web/
    │   └── ExpressServer.ts
    └── external/
        └── PaymentGateway.ts

This is an example, not a required directory structure.

Clean Architecture is primarily about dependency direction and separation of policy from implementation details, not specific folder names.

Repository Structure

clean-architecture-skills/
├── .claude-plugin/
│   └── marketplace.json
│
├── plugins/
│   ├── clean-architecture/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       └── clean-architecture/
│   │           └── SKILL.md
│   │
│   └── kent-beck-style/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── skills/
│           └── kent-beck-style/
│               └── SKILL.md
│
├── README.md
└── LICENSE

Philosophy

These skills are not intended to enforce architecture mechanically.

The goal is to help AI coding agents reason about questions such as:

• Is business logic coupled to infrastructure?
• Are dependencies pointing in the right direction?
• Is an abstraction actually useful?
• Is this design more complicated than the problem requires?
• Can this code be improved through a small refactoring instead of a rewrite?
• Does the code clearly communicate its intent?

Good architecture should make software easier to understand, change, test, and maintain — not merely add more layers.

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch

git checkout -b feature/amazing-feature

1. Commit your changes

git commit -m "Add amazing feature"

1. Push the branch

git push origin feature/amazing-feature

1. Open a Pull Request

References

Clean Architecture

• The Clean Architecture — Robert C. Martin
• Clean Architecture: A Craftsman's Guide to Software Structure and Design

Refactoring & Simple Design

• Refactoring — Martin Fowler
• Refactoring Catalog
• Implementation Patterns — Kent Beck
• Code Smells — Refactoring.Guru

Claude Code

• Claude Code Plugin Marketplaces

License

MIT License.

Free to use, modify, and distribute.