dotnet-claude-kit
AGENTS.md808 starsChanged 4 months agoMITView on GitHub
This file defines how Claude Code routes queries to specialist agents and how agents coordinate. Match user intent to agent. When multiple agents could handle a query, the first match wins. Agents load skills in dependency order. Core skills load first.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,843 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository57 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- .opencode/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/dotnet-rules.mdCursor rule
- api-versioningSkill
- arch-checkSkill
- architecture-advisorSkill
- aspireSkill
- authenticationSkill
- avaloniaSkill
- build-fixSkill
- cachingSkill
- checkpointSkill
- ci-cdSkill
- clean-architectureSkill
- code-reviewSkill
- configurationSkill
- console-cliSkill
- container-publishSkill
- convention-learnerSkill
- dddSkill
- dependency-injectionSkill
- desktop-mvvmSkill
- de-sloppifySkill
- dockerSkill
- dotnet-initSkill
- ef-coreSkill
- error-handlingSkill
- health-checkSkill
- httpclient-factorySkill
- instinct-systemSkill
- loggingSkill
- messagingSkill
- migrateSkill
- minimal-apiSkill
- modern-csharpSkill
- native-aotSkill
- openapiSkill
- opentelemetrySkill
- outdatedSkill
- planSkill
- project-setupSkill
- project-structureSkill
- resilienceSkill
- scaffoldSkill
- scalarSkill
- security-scanSkill
- serilogSkill
- specSkill
- tddSkill
- testingSkill
- token-reportSkill
- verifySkill
- vertical-sliceSkill
- workflow-masterySkill
- wrap-upSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 160
When two agents could handle a query:
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Routing & Orchestration
This file defines how Claude Code routes queries to specialist agents and how agents coordinate.
Agent Roster
| Agent | File | Primary Domain |
| dotnet-architect | agents/dotnet-architect.md | Architecture, project structure, module boundaries |
| api-designer | agents/api-designer.md | Minimal APIs, OpenAPI, versioning, rate limiting |
| ef-core-specialist | agents/ef-core-specialist.md | Database, queries, migrations, EF Core patterns |
| test-engineer | agents/test-engineer.md | Test strategy, xUnit, WebApplicationFactory, Testcontainers |
| security-auditor | agents/security-auditor.md | Authentication, authorization, OWASP, secrets |
| performance-analyst | agents/performance-analyst.md | Benchmarks, memory, async patterns, caching |
| devops-engineer | agents/devops-engineer.md | Docker, CI/CD, Aspire, deployment |
| code-reviewer | agents/code-reviewer.md | Multi-dimensional code review |
| build-error-resolver | agents/build-error-resolver.md | Autonomous build error fixing |
| refactor-cleaner | agents/refactor-cleaner.md | Systematic dead code removal and cleanup |
| app-engineer | agents/app-engineer.md | Console/CLI tools, desktop MVVM, Avalonia, Native AOT |
Routing Table
Match user intent to agent. When multiple agents could handle a query, the first match wins.
| User Intent Pattern | Primary Agent | Support Agent |
| "set up project", "folder structure", "architecture" | dotnet-architect | — |
| "add module", "split into modules", "bounded context" | dotnet-architect | — |
| "create endpoint", "API route", "OpenAPI", "swagger" | api-designer | — |
| "versioning", "rate limiting", "CORS" | api-designer | — |
| "database", "migration", "query", "DbContext", "EF" | ef-core-specialist | — |
| "write tests", "test strategy", "coverage" | test-engineer | — |
| "WebApplicationFactory", "Testcontainers", "xUnit" | test-engineer | — |
| "security", "authentication", "JWT", "OIDC", "authorize" | security-auditor | — |
| "performance", "benchmark", "memory", "profiling" | performance-analyst | — |
| "caching", "HybridCache", "output cache" | performance-analyst | — |
| "Docker", "container", "CI/CD", "pipeline", "deploy" | devops-engineer | — |
| "Aspire", "orchestration", "service discovery" | devops-engineer | — |
| "review this code", "PR review", "code quality" | code-reviewer | — |
| "choose architecture", "which architecture", "architecture decision" | dotnet-architect | — |
| "scaffold feature", "create feature", "add endpoint", "generate feature" | dotnet-architect | api-designer, ef-core-specialist |
| "init project", "setup project", "new project", "generate CLAUDE.md" | dotnet-architect | — |
| "health check", "analyze project", "project report" | code-reviewer | dotnet-architect |
| "review PR", "review changes", "code review", "PR review" | code-reviewer | — |
| "add migration", "ef migration", "update packages", "upgrade nuget" | ef-core-specialist | — |
| "conventions", "coding style", "detect patterns", "code consistency" | code-reviewer | — |
| "add feature" (architecture-appropriate) | dotnet-architect | api-designer, ef-core-specialist |
| "refactor" | code-reviewer | dotnet-architect |
| "build errors", "fix build", "won't compile" | build-error-resolver | — |
| "clean up", "dead code", "unused code", "de-sloppify" | refactor-cleaner | — |
| "console app", "CLI", "command line", "System.CommandLine", "dotnet tool", "exit code" | app-engineer | — |
| "desktop", "WPF", "WinForms", "Avalonia", "MAUI", "MVVM", "ViewModel", "XAML" | app-engineer | test-engineer |
| "Native AOT", "trimming", "single-file", "trim warning" | app-engineer | performance-analyst |
Skill Loading Order
Agents load skills in dependency order. Core skills load first.
Default Load Order (All Agents)
modern-csharp— Always loaded, baseline C# knowledge- Agent-specific skills (see agent files)
Per-Agent Skill Maps
| Agent | Skills |
| dotnet-architect | modern-csharp, architecture-advisor, project-structure, scaffold, project-setup + conditional: vertical-slice, clean-architecture, ddd |
| api-designer | modern-csharp, minimal-api, api-versioning, authentication, error-handling |
| ef-core-specialist | modern-csharp, ef-core, configuration, migrate |
| test-engineer | modern-csharp, testing |
| security-auditor | modern-csharp, authentication, configuration |
| performance-analyst | modern-csharp, caching |
| devops-engineer | modern-csharp, docker, ci-cd, aspire |
| code-reviewer | modern-csharp, code-review, convention-learner + contextual (loads relevant skills incl. clean-architecture, ddd based on files under review) |
| build-error-resolver | modern-csharp, build-fix + contextual: ef-core, dependency-injection |
| refactor-cleaner | modern-csharp, de-sloppify + contextual: testing, ef-core |
| app-engineer | modern-csharp + contextual: console-cli, desktop-mvvm, avalonia, native-aot, dependency-injection, configuration |
MCP Tool Preferences
Agents should prefer Roslyn MCP tools over file scanning to reduce token consumption.
| Task | Use MCP Tool | Instead Of |
| Find where a type is defined | find_symbol | Grep/Glob across all .cs files |
| Find all usages of a type | find_references | Grep for the type name |
| Find implementations of an interface | find_implementations | Searching for : IInterface |
| Understand inheritance | get_type_hierarchy | Reading multiple files |
| Understand project dependencies | get_project_graph | Parsing .csproj files manually |
| Review a type's API surface | get_public_api | Reading the full source file |
| Check for compilation errors | get_diagnostics | Running dotnet build and parsing output |
| Find unused code for cleanup | find_dead_code | Manual inspection of all files |
| Check for circular dependencies | detect_circular_dependencies | Manually tracing project references |
| Understand method call chains | get_dependency_graph | Reading multiple files and tracing calls |
| Check which types have tests | get_test_coverage_map | Manually searching for test files |
| Scan for .NET anti-patterns | detect_antipatterns | Manual code review across files |
| Find all callers of a method | find_callers | Grep for the method name |
| Find overrides of a virtual/abstract method | find_overrides | Searching for the override keyword |
| Get full signature, params, and XML docs | get_symbol_detail | Reading the entire source file |
| Read ONE method/member body | get_symbol_source | Reading the whole file for one method |
| See what's in a file before reading it | get_file_outline | Reading the file top to bottom |
| Audit NuGet packages and versions | get_nuget_packages | Parsing csproj/props files manually |
| Map routes and endpoint auth posture | get_endpoint_map | Grepping Map*/controller attributes |
| Audit DI lifetimes, duplicates, captive deps | get_di_registrations | Reading Program.cs and extension methods |
Cross-Agent Meta Skills
These meta and productivity skills are not tied to a specific agent — any agent can load them when the context calls for it:
| Skill | When to Load |
instinct-system | After ANY user correction, pattern detection across sessions, logging non-obvious discoveries; includes status/export/import modes |
wrap-up | Session start (load handoff) and session end (write handoff to .claude/handoff.md, capture learnings) |
checkpoint | Mid-session save before risky changes or task switches — commit + brief handoff |
workflow-mastery | Context running low, large codebase navigation, parallel workflows, subagent strategy |
convention-learner | Detect and enforce project-specific conventions in new code |
Model selection guidance lives in the always-loaded .claude/rules/agents.md — no skill load needed.
Meta Skill Routing
| User Intent Pattern | Skill |
| "learn from mistakes", "remember this", "log this", "gotcha", "show instincts", "what have you learned" | instinct-system |
| "wrap up", "done for today", "handoff", "start session", "load handoff" | wrap-up |
| "save progress", "checkpoint", "pause here" | checkpoint |
| "context", "running out of tokens", "too many files" | workflow-mastery |
| "review this", "what should I review", "blast radius" | code-review |
| "fix build loop", "keep fixing", "auto-fix" | build-fix |
Slash Commands
Commands map to skills and agents. Use these as shortcuts for common workflows.
Each workflow skill registers its own slash command and carries its methodology inline (the kit no longer splits workflows from their knowledge twins).
| Command | Supporting Skills | Primary Agent | Purpose |
/dotnet-init | project-setup | dotnet-architect (app-engineer for console/desktop) | Interactive project initialization |
/spec | — | — | Relentless questioning → agreed spec in docs/specs/ |
/plan | architecture-advisor | dotnet-architect | Architecture-aware planning (consumes approved specs) |
/verify | — | — | 7-phase verification pipeline |
/tdd | testing | test-engineer | Red-green-refactor workflow |
/scaffold | — | dotnet-architect | Architecture-aware feature scaffolding |
/code-review | convention-learner | code-reviewer | MCP-powered, blast-radius-prioritized code review |
/build-fix | — | build-error-resolver | Bounded build-fix and test-fix loops |
/checkpoint | — | — | Mid-session save (commit + handoff) |
/security-scan | — | security-auditor | OWASP + secrets + dependency audit |
/migrate | ef-core | ef-core-specialist | EF Core schema, .NET version, and NuGet migrations |
/health-check | — | code-reviewer | Graded project health report |
/de-sloppify | — | refactor-cleaner | Systematic code cleanup |
/wrap-up | instinct-system | — | Session handoff lifecycle (end + start) |
/outdated | — | — | Dependency health: staleness, CVEs, license traps |
/arch-check | architecture-advisor | dotnet-architect | Architecture conformance verification |
Instinct operations (status, export, import) are modes of the instinct-system skill — say "show instincts", "export instincts", or "import instincts".
Conflict Resolution
When two agents could handle a query:
- Architecture questions win over implementation — "How should I structure the payment module?" → dotnet-architect, even though api-designer could handle the endpoint part
- Specific beats general — "How do I optimize this EF query?" → ef-core-specialist, not performance-analyst
- Security concerns are always surfaced — Even when another agent is primary, flag security issues for the security-auditor
- Code review is holistic — The code-reviewer loads skills contextually based on what's in the PR
Token Budget Guidance
For detailed context management strategies, see the workflow-mastery skill (Context Discipline section).
- Small queries (single pattern/fix): Load 1-2 skills, use MCP tools for context
- Medium queries (feature implementation): Load 3-4 skills, use MCP tools to understand existing code
- Large queries (architecture review): Load all relevant skills, use
get_project_graphfirst to understand the solution shape
Response Patterns
All agents should:
- Start with the recommended approach — Don't enumerate all options equally
- Show code first, explain after — Developers prefer seeing the solution, then understanding why
- Flag anti-patterns proactively — If the user's existing code has issues, mention them
- Reference skills — Point to relevant skills for deeper reading
- Use MCP tools before reading files — Reduce token consumption
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.