{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/build-parallelism",
  "version": "1.0.0",
  "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: binlog MCP server tools (expensive_projects, expensive_targets, project_target_times); falls back to dotnet build -m, dotnet build /graph, binlog replay + grep.",
  "system_prompt_fragment": "## MSBuild Parallelism Model\n\n- `/maxcpucount` (or `-m`): number of worker nodes (processes)\n- Default: 1 node (sequential!). Always use `-m` for parallel builds\n- Recommended: `-m` without a number = use all logical processors\n- Each node builds one project at a time\n- Projects are scheduled based on dependency graph\n\n## Project Dependency Graph\n\n- MSBuild builds projects in dependency order (topological sort)\n- Critical path: longest chain of dependent projects determines minimum build time\n- Bottleneck: if project A depends on B, C, D and B takes 60s while C and D take 5s, B is the bottleneck\n- Diagnosis: replay binlog to diagnostic log with `performancesummary` and check Project Performance Summary — shows per-project time; grep for `node.*assigned` to check scheduling\n- Wide graphs (many independent projects) parallelize well; deep graphs (long chains) don't\n\n## Graph Build Mode (`/graph`)\n\n- `dotnet build /graph` or `msbuild /graph`\n- What it changes: MSBuild constructs the full project dependency graph BEFORE building\n- Benefits: better scheduling, avoids redundant evaluations, enables isolated builds\n- Limitations: all projects must use `<ProjectReference>` (no programmatic MSBuild task references)\n- When to use: large solutions with many projects, CI builds\n- When NOT to use: projects that dynamically discover references at build time\n\n## Optimizing Project References\n\n- Reduce unnecessary `<ProjectReference>` — each adds to the dependency chain\n- Use `<ProjectReference ... SkipGetTargetFrameworkProperties=\"true\">` to avoid extra evaluations\n- `<ProjectReference ... ReferenceOutputAssembly=\"false\">` for build-order-only dependencies\n- Consider if a ProjectReference should be a PackageReference instead (pre-built NuGet)\n- Use `solution filters` (`.slnf`) to build subsets of the solution\n\n## BuildInParallel\n\n- `<MSBuild Projects=\"@(ProjectsToBuild)\" BuildInParallel=\"true\" />` in custom targets\n- Without `BuildInParallel=\"true\"`, MSBuild task batches projects sequentially\n- Ensure `/maxcpucount` > 1 for this to have effect\n\n## Multi-threaded MSBuild Tasks\n\n- Individual tasks can run multi-threaded within a single project build\n- Tasks implementing `IMultiThreadableTask` can run on multiple threads\n- Tasks must declare thread-safety via `[MSBuildMultiThreadableTask]`\n\n## Analyzing Parallelism with Binlog\n\n### Primary: binlog MCP (preferred)\n\nUse the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the `binlog` MCP namespace):\n\n1. Use expensive_projects tool → find the slowest projects and compare individual vs total build time\n2. Use expensive_targets tool → find bottleneck targets\n3. Use project_target_times tool → drill into a specific project's target-level timing\n4. Ideal: build time should be much less than sum of project times (parallelism)\n5. If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others\n\n### Fallback: text-log replay (when MCP is unavailable)\n\nStep-by-step:\n\n1. Replay the binlog: `dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`\n2. Check Project Performance Summary at the end of `full.log`\n3. Ideal: build time should be much less than sum of project times (parallelism)\n4. If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others\n5. `grep 'Target Performance Summary' -A 30 full.log` → find the bottleneck targets\n6. Consider splitting large projects or optimizing the critical path\n\n## CI/CD Parallelism Tips\n\n- Use `-m` in CI (many CI runners have multiple cores)\n- Consider splitting solution into build stages for extreme parallelism\n- Use build caching (NuGet lock files, deterministic builds) to avoid rebuilding unchanged projects\n- `dotnet build /graph` works well with structured CI pipelines",
  "applicable_domains": [
    "code",
    "dotnet",
    "engineering"
  ],
  "invocation": [
    "/build-parallelism"
  ],
  "tags": [
    "dotnet-msbuild",
    "dotnet",
    "csharp",
    "microsoft"
  ],
  "authored_by": "anthropics",
  "source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/build-parallelism/SKILL.md",
  "lifecycle": "stable",
  "category": "dotnet",
  "provenance": {
    "source": "dotnet/skills",
    "source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/build-parallelism/SKILL.md",
    "author": "Microsoft / .NET Foundation",
    "license": "MIT",
    "notes": "Imported by scripts/import-anthropic-skills.py."
  }
}