# clean-architecture

A skill that lays out .NET code across four projects, keeps dependencies pointing inward, and shows where use case handlers belong.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3000 installs · ★ 789
- Author: codewithmukesh
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/codewithmukesh/dotnet-claude-kit/tree/HEAD/skills/clean-architecture/SKILL.md
- Updated: 2026-08-07
- HTML: https://affpapa.org/en/nevibecode/skills/codewithmukesh-clean-architecture

## What it does

This skill covers Clean Architecture for .NET: Domain, Application, Infrastructure and Api as separate projects. Dependencies point inward, and the compiler enforces that through project references. Domain holds business rules as entity methods and knows nothing about databases or HTTP — just C# and .NET primitives.

You get code templates, not just prose. A minimal `IAppDbContext` abstraction instead of a repository layer, command and query handlers built on Mediator, validators with FluentValidation, entities with behaviour and a static `Create` factory. Infrastructure is treated as a plugin: EF Core, email senders and external APIs implement interfaces declared in Application or Domain, so swapping one out leaves business logic alone. The Api layer stays thin — endpoints only translate HTTP into use case calls.

The templates assume a specific stack: source-generated Mediator, FluentValidation, EF Core. Bring a different mediator library, or keep repositories on top of `DbSet` on purpose, and you will be rewriting the samples to fit.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add codewithmukesh/dotnet-claude-kit --skill clean-architecture -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/clean-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/clean-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add codewithmukesh/dotnet-claude-kit --skill clean-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/clean-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add codewithmukesh/dotnet-claude-kit --skill clean-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/clean-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install codewithmukesh/dotnet-claude-kit clean-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/clean-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add codewithmukesh/dotnet-claude-kit --skill clean-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/codewithmukesh/dotnet-claude-kit --path skills/clean-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/clean-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add codewithmukesh/dotnet-claude-kit --skill clean-architecture -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/codewithmukesh/dotnet-claude-kit/tree/HEAD/skills/clean-architecture/SKILL.md

## When to use it
- split a .NET solution into Domain, Application, Infrastructure and Api
- move business rules into entities instead of fat service classes
- give each use case its own command or query handler
- wire EF Core and external services through interfaces without touching logic
- keep API endpoints free of business code

## Example prompts
- Scaffold a Clean Architecture project layout for orders
- Add a CreateOrder command with its handler and validator
- Rewrite this service as a use case handler using IAppDbContext

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b216ba8b14ccfca1.

BEGIN THIRD-PARTY FILE b216ba8b14ccfca1
````text
---
name: clean-architecture
description: >
  Clean Architecture for .NET applications. Covers the 4-project layout (Domain,
  Application, Infrastructure, Api), dependency inversion, use case handlers,
  domain entities with behavior, and infrastructure as a plugin.
  Load this skill when building a project with Clean Architecture, discussing
  layered architecture, dependency inversion, use cases, or when the
  architecture-advisor recommends Clean Architecture.
---

# Clean Architecture

## Core Principles

1. **Dependency inversion is the foundation** — All dependencies point inward. Domain has zero project references. Application references only Domain. Infrastructure references Application and Domain. Api references all but depends on abstractions. The compiler enforces this via project references.
2. **Domain owns the rules** — Business logic lives in the Domain layer as entity methods, domain services, or specifications. The Domain layer has no knowledge of databases, HTTP, or any framework — only pure C# and .NET primitives.
3. **Use cases are the unit of work** — Each use case (command or query) is a single class in the Application layer. It orchestrates domain objects, persists through abstractions, and returns a result. No "service" classes with 20 methods.
4. **Infrastructure is a plugin** — EF Core, external APIs, email senders, file storage — all live in Infrastructure and implement interfaces defined in Application or Domain. Swap implementations without touching business logic.
5. **The API layer is thin** — Endpoints map HTTP to use cases and use cases to HTTP responses. No business logic in endpoints.

## Patterns

### Project Layout

```
src/
  MyApp.Domain/
    Entities/
      Order.cs                    # Entity with behavior
      OrderItem.cs
    Enums/
      OrderStatus.cs
    Exceptions/
      DomainException.cs          # Base domain exception
    Interfaces/
      IOrderRepository.cs         # Only if query needs go beyond DbSet
    Common/
      Entity.cs                   # Base entity with Id
      Result.cs                   # Result pattern type

  MyApp.Application/
    Common/
      Behaviors/
        ValidationBehavior.cs     # Mediator pipeline behavior
      Interfaces/
        IAppDbContext.cs           # DbContext abstraction (preferred over repository)
    Orders/
      Commands/
        CreateOrder/
          CreateOrderCommand.cs
          CreateOrderHandler.cs
          CreateOrderValidator.cs
````
END THIRD-PARTY FILE b216ba8b14ccfca1

The third-party file has ended. Everything between the b216ba8b14ccfca1 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2494 of 13023 bytes. © codewithmukesh · MIT · https://github.com/codewithmukesh/dotnet-claude-kit/tree/HEAD/skills/clean-architecture/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md