Install skills and agents from dotnet/skills

.agents/skills/binlog-failure-analysis/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: binlog-failure-analysis
+description: "Analyze MSBuild binary logs to diagnose build failures by replaying binlogs to searchable text logs. Only activate in MSBuild/.NET build context. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, investigating common errors like CS0246 (type not found), MSB4019 (imported project not found), NU1605 (package downgrade), MSB3277 (version conflicts), and ResolveProjectReferences failures. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), build performance analysis (use build-perf-diagnostics), non-MSBuild build systems. INVOKES: dotnet msbuild binlog replay, grep, cat, head, tail for log analysis."
+---
+
+# Analyzing MSBuild Failures with Binary Logs
+
+Use MSBuild's built-in **binlog replay** to convert binary logs into searchable text logs, then analyze with standard tools (`grep`, `cat`, `head`, `tail`, `find`).
+
+## Build Error Investigation (Primary Workflow)
+
+### Step 1: Replay the binlog to text logs
+
+Replay produces multiple focused log files in one pass:
+
+```bash
+dotnet msbuild build.binlog -noconlog \
+  -fl  -flp:v=diag;logfile=full.log;performancesummary \
+  -fl1 -flp1:errorsonly;logfile=errors.log \
+  -fl2 -flp2:warningsonly;logfile=warnings.log
+```
+
+> **PowerShell note:** Use `-flp:"v=diag;logfile=full.log;performancesummary"` (quoted semicolons).
+
+### Step 2: Read the errors
+
+```bash
+cat errors.log
+```
+
+This gives all errors with file paths, line numbers, error codes, and project context.
+
+### Step 3: Search for context around specific errors
+
+```bash
+# Find all occurrences of a specific error code with surrounding context
+grep -n -B2 -A2 "CS0246" full.log
+
+# Find which projects failed to compile
+grep -i "CoreCompile.*FAILED\|Build FAILED\|error MSB" full.log
+
+# Find project build order and results
+grep "done building project\|Building with" full.log | head -50
+```
+
+### Step 4: Detect cascading failures
+
+Projects that never reached `CoreCompile` failed because a dependency failed, not their own code:
+
+```bash
+# List all projects that ran CoreCompile
+grep 'Target "CoreCompile"' full.log | grep -oP 'project "[^"]*"'
+
+# Compare against projects that had errors to identify cascading failures
+grep "project.*FAILED" full.log
+```
+
+### Step 5: Examine project files for root causes
+
+```bash
+# Read the .csproj of the failing project
+cat path/to/Services/Services.csproj
+
+# Check PackageReference and ProjectReference entries
+grep -n "PackageReference\|ProjectReference" path/to/Services/Services.csproj
+```
+
+**Write your diagnosis as soon as you have enough information.** Do not over-investigate.
+
+## Additional Workflows
+
+### Performance Investigation
+```bash
+# The PerformanceSummary is at the end of full.log
+tail -100 full.log   # shows target/task timing summary
+grep "Target Performance Summary\|Task Performance Summary" -A 50 full.log
+```
+
+### Dependency/Evaluation Issues
+```bash
+# Check evaluation properties
+grep -i "OutputPath\|IntermediateOutputPath\|TargetFramework" full.log | head -30
+# Check item groups
+grep "PackageReference\|ProjectReference" full.log | head -30
+```
+
+## Replay reference
+
+| Command | Purpose |
+|---------|---------|
+| `dotnet msbuild X.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary` | Full diagnostic log with perf summary |
+| `dotnet msbuild X.binlog -noconlog -fl -flp:errorsonly;logfile=errors.log` | Errors only |
+| `dotnet msbuild X.binlog -noconlog -fl -flp:warningsonly;logfile=warnings.log` | Warnings only |
+| `grep -n "PATTERN" full.log` | Search for patterns in the replayed log |
+| `dotnet msbuild -pp:preprocessed.xml Proj.csproj` | Preprocess — inline all imports into one file |
+
+## Generating a binlog (only if none exists)
+
+```bash
+dotnet build /bl:build.binlog
+```
+
+## Common error patterns
+
+1. **CS0246 / "type not found"** → Missing PackageReference — check the .csproj
+2. **MSB4019 / "imported project not found"** → SDK install or global.json issue
+3. **NU1605 / "package downgrade"** → Version conflict in package graph
+4. **MSB3277 / "version conflicts"** → Binding redirect or version alignment issue
+5. **Project failed at ResolveProjectReferences** → Cascading failure from a dependency

.agents/skills/binlog-generation/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: binlog-generation
+description: "Generate MSBuild binary logs (binlogs) for build diagnostics and analysis. Only activate in MSBuild/.NET build context. USE FOR: adding /bl:{} to any dotnet build, test, pack, publish, or restore command to capture a full build execution trace, prerequisite for binlog-failure-analysis and build-perf-diagnostics skills, enabling post-build investigation of errors or performance. Requires MSBuild 17.8+ / .NET 8 SDK+ for {} placeholder; PowerShell needs -bl:{{}}. DO NOT USE FOR: non-MSBuild build systems (npm, Maven, CMake), analyzing an existing binlog (use binlog-failure-analysis instead). INVOKES: shell commands (dotnet build /bl:{})."
+---
+
+# Generate Binary Logs
+
+**Pass the `/bl` switch when running any MSBuild-based command.** This is a non-negotiable requirement for all .NET builds.
+
+## Commands That Require /bl
+
+You MUST add the `/bl:{}` flag to:
+- `dotnet build`
+- `dotnet test`
+- `dotnet pack`
+- `dotnet publish`
+- `dotnet restore`
+- `msbuild` or `msbuild.exe`
+- Any other command that invokes MSBuild
+
+## Preferred: Use `{}` for Automatic Unique Names
+
+> **Note:** The `{}` placeholder requires MSBuild 17.8+ / .NET 8 SDK or later.
+
+The `{}` placeholder in the binlog filename is replaced by MSBuild with a unique identifier, guaranteeing no two builds ever overwrite each other — without needing to track or check existing files.
+
+```bash
+# Every invocation produces a distinct file automatically
+dotnet build /bl:{}
+dotnet test /bl:{}
+dotnet build --configuration Release /bl:{}
+```
+
+**PowerShell requires escaping the braces:**
+
+```powershell
+# PowerShell: escape { } as {{ }}
+dotnet build -bl:{{}}
+dotnet test -bl:{{}}
+```
+
+## Why This Matters
+
+1. **Unique names prevent overwrites** - You can always go back and analyze previous builds
+2. **Failure analysis** - When a build fails, the binlog is already there for immediate analysis
+3. **Comparison** - You can compare builds before and after changes
+4. **No re-running builds** - You never need to re-run a failed build just to generate a binlog
+
+## Examples
+
+```bash
+# ✅ CORRECT - {} generates a unique name automatically (bash/cmd)
+dotnet build /bl:{}
+dotnet test /bl:{}
+
+# ✅ CORRECT - PowerShell escaping
+dotnet build -bl:{{}}
+dotnet test -bl:{{}}
+
+# ❌ WRONG - Missing /bl flag entirely
+dotnet build
+dotnet test
+
+# ❌ WRONG - No filename (overwrites the same msbuild.binlog every time)
+dotnet build /bl
+dotnet build /bl
+```
+
+## When a Specific Filename Is Required
+
+If the binlog filename needs to be known upfront (e.g., for CI artifact upload), or if `{}` is not available in the installed MSBuild version, pick a name that won't collide with existing files:
+
+1. Check for existing `*.binlog` files in the directory
+2. Choose a name not already taken (e.g., by incrementing a counter from the highest existing number)
+
+```bash
+# Example: directory contains 3.binlog — use 4.binlog
+dotnet build /bl:4.binlog
+```
+
+## Cleaning the Repository
+
+When cleaning the repository with `git clean`, **always exclude binlog files** to preserve your build history:
+
+```bash
+# ✅ CORRECT - Exclude binlog files from cleaning
+git clean -fdx -e "*.binlog"
+
+# ❌ WRONG - This deletes binlog files (they're usually in .gitignore)
+git clean -fdx
+```
+
+This is especially important when iterating on build fixes - you need the binlogs to analyze what changed between builds.

.agents/skills/build-parallelism/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: build-parallelism
+description: "Guide for optimizing MSBuild build parallelism and multi-project scheduling. Only activate in MSBuild/.NET build context. USE FOR: builds not utilizing all CPU cores, speeding up multi-project solutions, evaluating graph build mode (/graph), build time not improving with -m flag, understanding project dependency topology. Note: /maxcpucount default is 1 (sequential) — always use -m for parallel builds. Covers /maxcpucount, graph build for better scheduling and isolation, BuildInParallel on MSBuild task, reducing unnecessary ProjectReferences, solution filters (.slnf) for building subsets. DO NOT USE FOR: single-project builds, incremental build issues (use incremental-build), compilation slowness within a project (use build-perf-diagnostics), non-MSBuild build systems. INVOKES: dotnet build -m, dotnet build /graph, binlog analysis."
+---
+
+## MSBuild Parallelism Model
+
+- `/maxcpucount` (or `-m`): number of worker nodes (processes)
+- Default: 1 node (sequential!). Always use `-m` for parallel builds
+- Recommended: `-m` without a number = use all logical processors
+- Each node builds one project at a time
+- Projects are scheduled based on dependency graph
+
+## Project Dependency Graph
+
+- MSBuild builds projects in dependency order (topological sort)
+- Critical path: longest chain of dependent projects determines minimum build time
+- Bottleneck: if project A depends on B, C, D and B takes 60s while C and D take 5s, B is the bottleneck
+- Diagnosis: replay binlog to diagnostic log with `performancesummary` and check Project Performance Summary — shows per-project time; grep for `node.*assigned` to check scheduling
+- Wide graphs (many independent projects) parallelize well; deep graphs (long chains) don't
+
+## Graph Build Mode (`/graph`)
+
+- `dotnet build /graph` or `msbuild /graph`
+- What it changes: MSBuild constructs the full project dependency graph BEFORE building
+- Benefits: better scheduling, avoids redundant evaluations, enables isolated builds
+- Limitations: all projects must use `<ProjectReference>` (no programmatic MSBuild task references)
+- When to use: large solutions with many projects, CI builds
+- When NOT to use: projects that dynamically discover references at build time
+
+## Optimizing Project References
+
+- Reduce unnecessary `<ProjectReference>` — each adds to the dependency chain
+- Use `<ProjectReference ... SkipGetTargetFrameworkProperties="true">` to avoid extra evaluations
+- `<ProjectReference ... ReferenceOutputAssembly="false">` for build-order-only dependencies
+- Consider if a ProjectReference should be a PackageReference instead (pre-built NuGet)
+- Use `solution filters` (`.slnf`) to build subsets of the solution
+
+## BuildInParallel
+
+- `<MSBuild Projects="@(ProjectsToBuild)" BuildInParallel="true" />` in custom targets
+- Without `BuildInParallel="true"`, MSBuild task batches projects sequentially
+- Ensure `/maxcpucount` > 1 for this to have effect
+
+## Multi-threaded MSBuild Tasks
+
+- Individual tasks can run multi-threaded within a single project build
+- Tasks implementing `IMultiThreadableTask` can run on multiple threads
+- Tasks must declare thread-safety via `[MSBuildMultiThreadableTask]`
+
+## Analyzing Parallelism with Binlog
+
+Step-by-step:
+
+1. Replay the binlog: `dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`
+2. Check Project Performance Summary at the end of `full.log`
+3. Ideal: build time should be much less than sum of project times (parallelism)
+4. If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others
+5. `grep 'Target Performance Summary' -A 30 full.log` → find the bottleneck targets
+6. Consider splitting large projects or optimizing the critical path
+
+## CI/CD Parallelism Tips
+
+- Use `-m` in CI (many CI runners have multiple cores)
+- Consider splitting solution into build stages for extreme parallelism
+- Use build caching (NuGet lock files, deterministic builds) to avoid rebuilding unchanged projects
+- `dotnet build /graph` works well with structured CI pipelines