Make Claude Code an expert .NET developer.
47 skills • 10 specialist agents • 16 slash commands • 10 rules • 5 project templates • 20 MCP tools • automation hooks
Built for .NET 10 / C# 14. Architecture-aware. Token-efficient.
📖 Full Guide • Installation • Quick Start • 10x Features • Commands • Skills • Agents • Rules • Templates • MCP Server • Contributing
How I Use dotnet-claude-kit: Making Claude Code Write Senior-Level .NET →
The complete walkthrough: install and update the plugin, what happens in your first session, the everyday feature workflow, how the Roslyn MCP server cuts token usage, which commands keep a codebase healthy, plus FAQ and troubleshooting.
This README is the reference. The guide is how to actually use it.
Claude Code is powerful, but out of the box it doesn't know your .NET conventions. It generates DateTime.Now instead of TimeProvider. It wraps EF Core in repository abstractions. It picks an architecture without asking about your domain. It reads entire source files when a Roslyn query would cost 10x fewer tokens.
dotnet-claude-kit fixes all of that.
A curated knowledge and action layer that sits between Claude Code and your .NET project. Drop a single CLAUDE.md into your repo and Claude instantly knows:
- Which architecture fits your project (VSA, Clean Architecture, DDD, Modular Monolith)
- How to write modern C# 14 with primary constructors, collection expressions, and records
- How to build minimal APIs with
IEndpointGroupauto-discovery,TypedResults, and proper OpenAPI metadata - How to use EF Core without repository wrappers, with compiled queries and interceptors
- How to test with
WebApplicationFactory+Testcontainersinstead of in-memory fakes - How to navigate your codebase via Roslyn semantic analysis instead of expensive file reads
- How to scaffold complete features, run health checks, review PRs, and enforce conventions
No configuration. No setup wizards. Just copy one file and go.
An action layer on top of the knowledge layer — Claude doesn't just know the right patterns, it actively applies and enforces them:
| Capability | What It Does |
|---|---|
| Surgical Code Analysis | 20 Roslyn-powered MCP tools with guaranteed bounded responses. get_symbol_source reads ONE method body instead of the whole file. get_file_outline shows what's in a file before reading it. Every list-returning tool is capped with TotalFound — no tool can blow your context window. |
| Architecture Enforcement | /arch-check verifies the code still matches its declared architecture (VSA, Clean, DDD, Modular Monolith): dependency direction, layer violations, module leaks, cycles — with file:line evidence and fixes. |
| Dependency Health | /outdated reports stale packages, CVEs, and commercial-license traps (MediatR 13+, MassTransit 9+, FluentAssertions 8+, AutoMapper 15+) before an innocent update-all changes your legal position. |
| Security Mapping | get_endpoint_map inventories every route with its auth posture (authorized/anonymous/unmarked) in one token-cheap call — /security-scan starts every auth audit there. |
| DI X-Ray | get_di_registrations maps every service registration with lifetimes, duplicate detection, and captive-dependency risks (singleton holding scoped). |
| Agents That Learn | Specialist agents carry memory: project — the code reviewer, architect, and security auditor learn your conventions across sessions instead of rediscovering them. The reviewer is tool-enforced read-only; the cleanup agent works in an isolated worktree. |
| Scaffolding | One command → complete feature with Result pattern, validation, OpenAPI metadata, pagination, CancellationToken, and tests. 9-point checklist enforced. All 4 architectures. |
| Health Check | Automated codebase analysis using MCP tools: anti-pattern scan, diagnostics, dead code detection, test coverage → graded report card. |
| PR Review | Multi-dimensional code review: anti-patterns, diagnostics, API surface changes, blast radius, architecture compliance, test coverage. |
| Convention Learning | Detects project-specific patterns (naming, structure, modifiers) and enforces them in new code. Adapts to your codebase. |
| Active Hooks | Automated quality scripts — format on edit, destructive-command guard, restore on .csproj change — tested on Windows and Linux in CI. |
| Always Current | Every package recommendation verified against NuGet with licensing-trap warnings, and a .NET 11 preview watch so guidance never rots. |
| Metric | Without Kit | With Kit | Impact |
|---|---|---|---|
| Architecture decisions | Claude picks randomly | Asks questions, recommends with rationale | Correct architecture from day one |
| Code quality | Generic C#, legacy patterns | Modern C# 14 with idiomatic .NET 10 | Zero "fix this pattern" revision cycles |
| Codebase navigation | Reads entire files (500-2000+ tokens each) | Roslyn MCP queries (30-150 tokens each) | ~10x token savings on exploration |
| Anti-patterns generated | DateTime.Now, repository-over-EF, new HttpClient() |
TimeProvider, direct DbContext, IHttpClientFactory |
Production-ready on first generation |
| Testing approach | In-memory fakes, mocked everything | WebApplicationFactory + Testcontainers |
Tests that catch real bugs |
| Production resilience | No retry, no circuit breakers | Polly v8 pipelines with telemetry | Handles transient failures automatically |
The result: Less time reviewing and correcting Claude's output. More time shipping features.
Prefer a narrated walkthrough with screenshots and troubleshooting? Read the complete installation and usage guide.
Install as a Claude Code plugin — all 47 skills (including 16 slash-command workflows), 10 agents, hooks, and MCP config activate globally. The 10 rules ship in this repo for you to copy into your project's .claude/rules/:
# In your terminal — install the Roslyn MCP server
dotnet tool install -g CWM.RoslynNavigatormacOS/Linux: If the server fails with "No .NET SDKs were found", set
DOTNET_ROOTto your .NET installation root (e.g./usr/local/share/dotnet). See the MCP server troubleshooting guide.
Then inside a Claude Code session:
# Add the marketplace and install the plugin
/plugin marketplace add codewithmukesh/dotnet-claude-kit
/plugin install dotnet-claude-kit
For local development/testing (loads directly from disk, no install needed):
claude --plugin-dir /path/to/dotnet-claude-kitNavigate to your project directory (existing or empty) and run:
/dotnet-initExisting project? It detects your solution, scans .csproj SDKs, reads your tech stack from config, asks architecture questions, and generates a customized CLAUDE.md.
Greenfield project? It asks what you're building, scaffolds the full solution structure (dotnet new sln, projects, Directory.Build.props, src/ and tests/ folders), then generates CLAUDE.md. Follow up with /scaffold to add your first feature.
No manual template copying needed.
Manual Template Copy (Alternative)
If you prefer manual setup, copy the template matching your project type:
cp templates/web-api/CLAUDE.md ./CLAUDE.md # REST API
cp templates/modular-monolith/CLAUDE.md ./CLAUDE.md # Multi-module system
cp templates/blazor-app/CLAUDE.md ./CLAUDE.md # Blazor app
cp templates/worker-service/CLAUDE.md ./CLAUDE.md # Background workers
cp templates/class-library/CLAUDE.md ./CLAUDE.md # NuGet packagesReplace [ProjectName], update tech stack, choose your architecture.
Start Claude Code — 47 skills, 10 agents, and 20 MCP tools activate automatically. Copy the 10 rules into your project's .claude/rules/ to make them always-loaded.
That's it. Claude now writes .NET code the way a senior .NET engineer would.
Manual Install (Alternative)
If you prefer to clone the repo and wire things up manually:
# 1. Install the MCP server globally
dotnet tool install -g CWM.RoslynNavigator
# 2. Register it in Claude Code at user scope (available in ALL projects)
claude mcp add --scope user cwm-roslyn-navigator -- cwm-roslyn-navigator --solution ${workspaceFolder}
# 3. Clone the kit
git clone https://github.com/codewithmukesh/dotnet-claude-kit.git
# 4. Load as a local plugin (or copy a template manually)
claude --plugin-dir ./dotnet-claude-kit// Claude generates this
public class OrderService
{
private readonly IOrderRepository _repo; // unnecessary abstraction over EF Core
public async Task<Order> CreateOrder(CreateOrderDto dto)
{
var order = new Order();
order.CreatedAt = DateTime.Now; // wrong — use TimeProvider
order.Items = dto.Items.ToList();
await _repo.AddAsync(order);
return order; // leaks domain entity to API
}
}// Claude generates this
public static class CreateOrder
{
public record Command(string CustomerId, List<OrderItemDto> Items) : IRequest<Result<Response>>;
public record Response(Guid Id, decimal Total, DateTimeOffset CreatedAt);
internal sealed class Handler(AppDbContext db, TimeProvider clock)
: IRequestHandler<Command, Result<Response>>
{
public async Task<Result<Response>> Handle(Command request, CancellationToken ct)
{
var order = Order.Create(request.CustomerId, request.Items, clock.GetUtcNow());
db.Orders.Add(order);
await db.SaveChangesAsync(ct);
return Result.Success(new Response(order.Id, order.Total, order.CreatedAt));
}
}
}// Each endpoint group auto-discovered — Program.cs never changes
public sealed class OrderEndpoints : IEndpointGroup
{
public void Map(IEndpointRouteBuilder app)
{
var group = app.MapGroup("/api/orders").WithTags("Orders");
group.MapPost("/", CreateOrderHandler)
.WithName("CreateOrder").Produces<CreateOrder.Response>(201)
.ProducesValidationProblem()
.AddEndpointFilter<ValidationFilter<CreateOrder.Command>>();
}
}Result pattern. FluentValidation with endpoint filters. IEndpointGroup auto-discovery. TypedResults with OpenAPI metadata. CancellationToken everywhere. Sealed handlers. TimeProvider injection. DbContext directly. Every pattern comes from the skills in this kit.
Shortcut workflows that orchestrate skills and agents. Type the command and Claude handles the rest. These are workflow skills — each lives at skills/<name>/SKILL.md, registers its /name automatically, and carries its methodology inline (no separate knowledge twin to load).
| Command | Purpose | Works With |
|---|---|---|
/dotnet-init |
Project setup (existing or greenfield) — detects or scaffolds, then generates CLAUDE.md | project-setup skill, dotnet-architect agent |
/spec |
Relentless questioning until human + AI agree on a persisted spec (docs/specs/) |
feeds /plan and /tdd |
/plan |
Architecture-aware planning — consumes approved specs | architecture-advisor skill, dotnet-architect agent |
/verify |
7-phase verification: build → analyzers → antipatterns → tests → security → format → diff | — |
/tdd |
Red-green-refactor with xUnit + Testcontainers | testing skill, test-engineer agent |
/scaffold |
Architecture-aware feature scaffolding (all 4 architectures, per-architecture templates included) | dotnet-architect agent |
/code-review |
MCP-powered, blast-radius-prioritized code review | code-reviewer agent |
/build-fix |
Bounded build-fix and test-fix loops with progress detection | build-error-resolver agent |
/checkpoint |
Mid-session save: commit + brief handoff note | — |
/security-scan |
OWASP + secrets + vulnerable dependency audit | security-auditor agent |
/migrate |
EF Core schema, .NET version, and NuGet migrations with rollback | ef-core-specialist agent |
/health-check |
Project health assessment with letter grades (A-F) | code-reviewer agent |
/de-sloppify |
Systematic cleanup: format → dead code → analyzers → sealed | refactor-cleaner agent |
/wrap-up |
Session handoff lifecycle: end-of-session ritual + session-start loading | instinct-system skill |
/outdated |
Dependency health: outdated packages, CVEs, and commercial-license traps | get_nuget_packages MCP tool |
/arch-check |
Architecture conformance: dependency direction, layer violations, module leaks | get_project_graph MCP tool |
Instinct operations (status, export, import) are modes of the instinct-system skill — say "show instincts", "export instincts", or "import instincts".
Project-level conventions that apply to every interaction once loaded. Rules ship in this repo (and via the templates) — copy them into your project's .claude/rules/ to make them always-loaded.
| Rule | Enforces |
|---|---|
| coding-style | C# 14 conventions, file-scoped namespaces, primary constructors, sealed, records |
| architecture | Ask before recommending, no repo over EF, feature folders, dependency direction |
| security | No hardcoded secrets, parameterized queries, explicit auth, HTTPS |
| testing | Integration-first, WebApplicationFactory + Testcontainers, AAA pattern |
| performance | CancellationToken propagation, TimeProvider, IHttpClientFactory, HybridCache |
| error-handling | Result pattern, ProblemDetails, no broad catch, boundary validation |
| git-workflow | Conventional commits, atomic commits, never force-push main |
| agents | MCP-first, subagent routing, skill loading order |
| hooks | Auto-accept formatting, never skip pre-commit hooks |
| packages | Always use latest stable NuGet versions, never rely on training data versions |
Code-heavy reference files that teach Claude .NET best practices. Each skill is under 400 lines with concrete code examples, anti-patterns (BAD/GOOD comparisons), and decision guides. (The other 16 of the 47 skills are the workflow orchestrators documented under Slash Commands.)
| Category | Skills | What Claude Learns |
|---|---|---|
| Architecture | architecture-advisor, vertical-slice, clean-architecture, ddd, project-structure | Ask before recommending. VSA for CRUD, CA for medium complexity, DDD for rich domains, Modular Monolith for bounded contexts. |
| Core Language | modern-csharp | Primary constructors, collection expressions, field keyword, records, pattern matching, spans |
| Web / API | minimal-api, api-versioning, authentication, openapi, scalar, httpclient-factory | MapGroup, TypedResults, endpoint filters, JWT/OIDC, Asp.Versioning, built-in OpenAPI, typed HTTP clients |
| Data | ef-core | No repository wrappers. Compiled queries, interceptors, ExecuteUpdateAsync, value converters |
| Resilience | error-handling, resilience, caching, messaging | Result pattern, Polly v8 pipelines, HybridCache, Wolverine/MassTransit, outbox, sagas |
| Observability | logging, serilog, opentelemetry | Health checks and correlation IDs, Serilog structured logging, OpenTelemetry traces and metrics |
| Testing | testing | xUnit v3, WebApplicationFactory, Testcontainers, Verify snapshots |
| DevOps | docker, container-publish, ci-cd, aspire | Multi-stage builds, Dockerfile-less SDK publishing, GitHub Actions, .NET Aspire orchestration |
| Cross-cutting | dependency-injection, configuration | Keyed services, Options pattern, secrets management |
| Project Setup | project-setup, convention-learner | Solution scaffolding, convention detection and enforcement |
| Workflow & Learning | workflow-mastery, instinct-system | Parallel worktrees, plan mode strategy, subagent patterns, context discipline; confidence-scored instincts, correction capture, discovery logging |
Specialist agents that Claude routes queries to automatically. Each agent loads the right skills, uses MCP tools for context, and knows its boundaries.
| Agent | When It Activates | What It Does |
|---|---|---|
| dotnet-architect | "set up project", "architecture", "scaffold feature", "init project" | Runs the architecture questionnaire, scaffolds features, initializes projects |
| api-designer | "create endpoint", "OpenAPI", "versioning" | Designs minimal API endpoints with proper metadata, versioning, and auth |
| ef-core-specialist | "database", "migration", "query", "DbContext" | Optimizes queries, configures entities, manages migrations safely |
| test-engineer | "write tests", "test strategy", "coverage" | Integration-first testing with real databases via Testcontainers |
| security-auditor | "security", "authentication", "JWT" | OWASP top 10, auth configuration, secrets management |
| performance-analyst | "performance", "benchmark", "caching" | Identifies hot paths, configures HybridCache, async optimization |
| devops-engineer | "Docker", "CI/CD", "Aspire", "deploy" | Multi-stage Dockerfiles, GitHub Actions pipelines, Aspire orchestration |
| code-reviewer | "review this code", "PR review", "health check", "conventions" | MCP-driven multi-dimensional review, convention detection and enforcement |
| build-error-resolver | "fix build", "build errors", "won't compile" | Autonomous build-fix loop: parse errors → categorize → fix → rebuild |
| refactor-cleaner | "clean up", "dead code", "de-sloppify" | Systematic cleanup: dead code removal, formatting, sealing, CancellationToken |
Drop-in CLAUDE.md files that configure Claude for specific project types. Copy one file, replace the placeholders, done.
| Template | For | Includes |
|---|---|---|
| web-api | REST APIs, microservices | Architecture options (VSA/CA/DDD), minimal APIs, EF Core, testing |
| modular-monolith | Multi-module systems | Module boundaries, per-module DbContext, Wolverine/MassTransit integration events |
| blazor-app | Blazor Server / WASM / Auto | Component organization, render mode strategy, bUnit testing |
| worker-service | Background processing | BackgroundService patterns, Wolverine/MassTransit consumers, proper cancellation |
| class-library | NuGet packages, shared libraries | Public API design, XML docs, semantic versioning, SourceLink |
Token-efficient codebase navigation via Roslyn semantic analysis. Instead of Claude reading entire source files (500-2000+ tokens each), it queries the MCP server for exactly what it needs (30-150 tokens).
| Tool | What It Does | Replaces |
|---|---|---|
find_symbol |
Locate type/method definitions | Grep/Glob across all .cs files |
find_references |
Find all usages of a symbol | Grep for the type name |
find_implementations |
Find interface implementors | Searching for : IInterface |
find_callers |
Find all methods calling a method | Manual grep for method name |
find_overrides |
Find overrides of virtual/abstract methods | Searching for override keyword |
get_type_hierarchy |
Inheritance chain + interfaces | Reading multiple files |
get_project_graph |
Solution dependency tree | Parsing .csproj files manually |
get_public_api |
Public API without full file | Reading entire source files |
get_symbol_detail |
Full signature, params, XML docs | Reading entire source files |
get_diagnostics |
Compiler warnings/errors | Running dotnet build and parsing |
detect_antipatterns |
10 .NET anti-pattern rules | Manual code review |
find_dead_code |
Unused types, methods, properties | Manual inspection of all files |
detect_circular_dependencies |
Project and type-level cycles | Manually tracing references |
get_dependency_graph |
Method call chain visualization | Reading multiple files and tracing |
get_test_coverage_map |
Heuristic test coverage mapping | Searching for test files manually |
get_symbol_source |
Exact source of ONE member (bounded, capped) | Reading the whole file for one method |
get_file_outline |
Type/member skeleton of a file, no bodies | Reading the file to see what's in it |
get_nuget_packages |
PackageReference inventory with CPM awareness | Parsing csproj/props files manually |
get_endpoint_map |
Route inventory with auth posture per endpoint | Grepping Map*/controllers by hand |
get_di_registrations |
DI map: lifetimes, duplicates, captive risks | Reading Program.cs and extensions |
The MCP server starts automatically via .mcp.json. No manual setup required.
See mcp/CWM.RoslynNavigator/README.md for details.
Living reference documents updated per .NET release:
| Document | Purpose |
|---|---|
| dotnet-whats-new | .NET 10 / C# 14 features and how to use them |
| common-antipatterns | Patterns Claude should never generate |
| package-recommendations | Vetted NuGet packages with rationale and "when NOT to use" |
| breaking-changes | .NET migration gotchas |
| common-infrastructure | Copy-paste implementations: Result, ValidationFilter, IExceptionHandler, IEndpointGroup + MapEndpoints, pagination |
| mediatr-to-mediator-migration | Step-by-step MediatR → Mediator (MIT, source-generated) migration guide |
| decisions/ | Architecture Decision Records explaining every default |
Three Claude Code hooks run automatically (declared in hooks/hooks.json); the rest are git pre-commit hooks and workflow utilities — see hooks/README.md for setup:
| Script | Kind | What It Does |
|---|---|---|
pre-bash-guard.sh |
Claude Code hook — PreToolUse (Bash) | Blocks destructive git ops (force push, reset --hard), warns on risky commands |
post-edit-format.sh |
Claude Code hook — PostToolUse (*.cs) | Auto-formats C# files after edits |
post-scaffold-restore.sh |
Claude Code hook — PostToolUse (*.csproj) | dotnet restore after project file changes |
pre-commit-format.sh |
Git pre-commit (manual install) | dotnet format --verify-no-changes ensures consistent formatting |
pre-commit-antipattern.sh |
Git pre-commit (manual install) | Detects DateTime.Now, async void, new HttpClient() in staged files |
post-test-analyze.sh |
Utility (pipe test output) | Parses test results and outputs actionable summary |
pre-build-validate.sh |
Utility (run before builds) | Validates project structure (solution file, Directory.Build.props, test projects) |
Every default is documented with an ADR explaining why:
| Decision | Default | Why |
|---|---|---|
| Architecture | Advisor-driven | Asks questions first, then recommends VSA, CA, DDD, or Modular Monolith (ADR-005) |
| Error handling | Result pattern | Exceptions are for exceptional cases (ADR-002) |
| ORM | EF Core | Best developer experience for most scenarios (ADR-003) |
| Caching | HybridCache | Built-in stampede protection, L1+L2 (ADR-004) |
| APIs | Minimal APIs | Lighter, composable, architecture-agnostic |
| Testing | Integration-first | WebApplicationFactory + Testcontainers over in-memory fakes |
| Time | TimeProvider |
Testable, injectable, no more DateTime.Now |
| HTTP clients | IHttpClientFactory |
No more new HttpClient() socket exhaustion |
dotnet-claude-kit/
├── CLAUDE.md # Instructions for developing THIS repo
├── AGENTS.md # Agent routing & orchestration
├── agents/ # 10 specialist agents
├── skills/ # 47 skills (incl. 16 slash-command workflows)
├── .claude/rules/ # 10 always-loaded rules
├── templates/ # 5 drop-in CLAUDE.md templates
├── knowledge/ # Living reference documents + ADRs
├── mcp/CWM.RoslynNavigator/ # Roslyn MCP server (20 tools)
├── mcp-configs/ # MCP server config templates
├── hooks/ # Claude Code hooks + git hooks + utilities
├── docs/ # Shorthand + longform guides
├── .mcp.json # MCP server registration
├── .claude-plugin/ # Plugin marketplace manifests
├── .cursor/rules/ # Cursor IDE compatibility
├── .codex/ # Codex CLI compatibility
├── opencode.json # OpenCode config (MCP + rules)
├── .opencode/ # OpenCode compatibility
└── .github/workflows/ # CI validation
dotnet-claude-kit works with multiple AI coding tools:
| Platform | Config File | What It Provides |
|---|---|---|
| Claude Code | .claude-plugin/plugin.json |
Full integration: skills, agents, commands, rules, hooks, MCP |
| Cursor | .cursor/rules/dotnet-rules.md |
Consolidated .NET rules for Cursor IDE |
| Codex CLI | .codex/AGENTS.md |
Agent configuration pointing to skills and agents |
| OpenCode | opencode.json + .opencode/AGENTS.md |
Roslyn MCP server, consolidated rules, and agent/skill catalog |
| Guide | For | Content |
|---|---|---|
| 📖 How I Use dotnet-claude-kit | Start here | Install, update, first session, everyday feature workflow, Roslyn MCP token savings, health commands, FAQ, troubleshooting |
| Shorthand Guide | Quick reference | All commands, skills, agents, hooks, MCP tools with cross-reference matrix |
| Longform Guide | Deep dive | Workflows, token optimization, autonomous patterns, troubleshooting |
See CONTRIBUTING.md for how to add skills, agents, commands, rules, knowledge, templates, and MCP tools.
📖 Read the complete guide: How I Use dotnet-claude-kit
Built by Mukesh Murugan • Powered by Claude Code