.NET Architecture Skills

English | 中文

A skill plugin for Claude Code and OpenAI Codex that enforces Microsoft's official .NET NuGet package separation pattern — automatically splitting foundational class libraries into an Abstractions contract package and an implementation package.

Why This Exists

In the .NET ecosystem, Microsoft ships packages in pairs:

• Microsoft.Extensions.Logging.Abstractions + Microsoft.Extensions.Logging
• Microsoft.Extensions.Configuration.Abstractions + Microsoft.Extensions.Configuration
• Microsoft.AspNetCore.Http.Abstractions + Microsoft.AspNetCore.Http

This pattern enforces Dependency Inversion Principle (DIP) at the package level — upstream callers depend only on the abstractions contract, never on concrete implementations. But teams often bundle interfaces and implementations together in a single project, creating tight coupling and circular dependencies.

This skill codifies that pattern so AI coding agents apply it automatically whenever you create or modify a .NET foundational library.

Problems it solves:

• Keeps global CLAUDE.md clean — skills are enabled on demand
• Automatically distinguishes project types: applies to class libraries, ignores API/Web/Host layers
• Enforces dependency inversion, decoupled layering, and zero circular references
• Aligns with Microsoft's official package design conventions

Built-in Skills

Skill	What It Does
microsoft-abstractions	Enforces {Company}.{Module}.Abstractions + {Company}.{Module} split. Defines what belongs in each package (interfaces, abstract classes, enums, DTOs vs. implementation, DI registration, third-party adapters). Automatically excludes API, Web, Host, and Application layers.

Installation

Claude Code

Add the marketplace from the Claude Code terminal:

/plugin marketplace add TheodoreCheung/dotnet-architecture-skills

Or add it locally:

/plugin marketplace add ./path/to/dotnet-architecture-skills

Then install the plugin:

/plugin install dotnet-architecture-skills

Codex

Add the marketplace:

codex plugin marketplace add TheodoreCheung/dotnet-architecture-skills

Then install the plugin:

codex plugin install dotnet-architecture-skills

Project Structure

dotnet-architecture-skills/
├── .claude-plugin/
│   ├── marketplace.json        # Claude Code marketplace manifest
│   └── plugin.json             # Claude Code plugin manifest
├── .codex-plugin/
│   └── plugin.json             # Codex plugin manifest
├── skills/
│   └── microsoft-abstractions/
│       └── SKILL.md            # Skill definition (shared by both platforms)
├── README.md                   # English documentation
└── README.zh-CN.md             # Chinese documentation

Both Claude Code and Codex share the same skills/ directory — the SKILL.md format is compatible across both platforms.

How It Works

When you create or modify a .NET foundational class library, the skill steps through a four-stage process:

1. Diagnose — checks .csproj for Web/API/Host framework references to determine whether the project is in scope
2. Recommend — if applicable, proposes splitting into {Company}.{Module}.Abstractions and {Company}.{Module}
3. Execute — creates the two projects, distributes code according to the rules (interfaces/abstracts/enums/DTOs go to Abstractions; implementations/DI/adapters go to the implementation package)
4. Verify — cross-checks the Abstractions package for prohibited content (DB/Redis/MQ/File/Network I/O, third-party SDKs, service registration)

Abstractions Package Rules

Allowed:

• Public interfaces, abstract base classes
• Enums, constants, base entities, DTO base classes
• Custom attributes
• Logic-free static extension methods

Prohibited:

• Concrete business logic
• Database, Redis, MQ, file, or network I/O
• Third-party SDK dependencies, service registration, configuration reading
• Instantiable utility classes

Microsoft References

• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Configuration.Abstractions
• Microsoft.AspNetCore.Http.Abstractions

License

MIT