Agent skill
dev-dotnet-build
MSBuild diagnosis and optimization for .NET projects. Covers binlog analysis, incremental build fixes, common MSBuild antipatterns, and Directory.Build.props/targets organization. Referenced by dev-verification-backend and dotnet-build-resolver agent.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/dev-dotnet-build
SKILL.md
MSBuild Diagnosis & Optimization
Diagnose and fix .NET build failures, slow builds, and MSBuild configuration issues.
Stack: C#/.NET (MSBuild, NuGet, SDK-style projects)
When to Use
- Build failures that aren't simple compilation errors
- Slow builds / broken incremental builds
- Complex multi-project solution MSBuild issues
- Directory.Build.props/targets configuration problems
- MSBuild property/target ordering issues
Core Workflow
1. DIAGNOSE → Identify the error category
2. BINLOG → Generate and analyze binary log
3. FIX → Apply targeted fix
4. VERIFY → Rebuild and confirm
Phase 1: Generate Binary Log
Always start with a binlog for non-trivial build issues:
# Generate binlog
dotnet build /bl:build.binlog 2>&1 | tail -30
# Named binlog for before/after comparison
dotnet build /bl:before.binlog
# ... apply fix ...
dotnet build /bl:after.binlog
The binlog captures the full MSBuild evaluation — every property, item, target, and task. See binlog-analysis.md for deep analysis techniques.
Phase 2: Error Classification
| Error prefix | Category | Approach |
|---|---|---|
CS**** |
C# compiler | Read error location, fix code |
MSB**** |
MSBuild engine | Check project files, SDK, imports |
NU**** |
NuGet | Check packages, sources, versions |
NETSDK**** |
.NET SDK | Check SDK version, target framework |
| No prefix | Target/task failure | Check custom targets, tools |
Phase 3: Common Diagnosis Patterns
Missing or Wrong SDK
# Check installed SDKs
dotnet --list-sdks
# Check global.json pin
cat global.json
# Fix: update global.json or install correct SDK
dotnet new globaljson --sdk-version <version> --force
Property Override Issues
Properties set in the wrong order get overwritten. Check evaluation order:
# See the fully evaluated project (all imports resolved)
dotnet msbuild <project.csproj> -preprocess > evaluated.xml
Look for the same property being set multiple times — last one wins.
Target Ordering
# List all targets and their dependencies
dotnet msbuild <project.csproj> -targets 2>&1 | head -50
NuGet Resolution Failures
# Clear NuGet caches (resolves stale package issues)
dotnet nuget locals all --clear
# Restore with detailed verbosity
dotnet restore --verbosity detailed 2>&1 | tail -50
Missing Project References
# List all project references
dotnet list reference
# Check for broken references
find . -name "*.csproj" -exec grep -l "ProjectReference" {} + | \
xargs grep "ProjectReference" | grep -v "^Binary"
Phase 4: Fix and Verify
After applying a fix:
# Clean rebuild (eliminates stale artifacts)
dotnet clean
dotnet build 2>&1 | tail -30
# If build succeeds, run tests
dotnet test 2>&1 | tail -30
Build Performance
For slow builds, check:
# Performance summary
dotnet build /clp:PerformanceSummary 2>&1 | tail -40
# Detailed timing
dotnet build /bl:perf.binlog
# Analyze target execution times in the binlog
See incremental-builds.md for fixing broken incremental builds.
Reference Docs
- binlog-analysis.md — Binary log generation, reading, and comparison
- incremental-builds.md — Fix broken incremental builds
- msbuild-antipatterns.md — 15+ common MSBuild mistakes
- directory-build-organization.md — Props/targets hierarchy and organization
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?