# binlog-generation

The skill makes your agent add /bl:{} to every MSBuild command, so each build leaves a .binlog with a full trace you can inspect after a failure or a slowdown.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3500 installs · ★ 5730
- Author: dotnet
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/binlog-generation

## What it does

It appends the `/bl:{}` switch to anything that runs MSBuild: `dotnet build`, `test`, `pack`, `publish`, `restore`, and bare `msbuild`. A `.binlog` stays behind with the whole execution trace. Your agent does it on every invocation, no prompting required.

The `{}` placeholder gets swapped for a unique identifier, so back-to-back builds never overwrite one file. That needs MSBuild 17.8+ or .NET 8 SDK and newer — on older versions the placeholder stays literal and you pick a name yourself; the skill suggests scanning for existing `*.binlog` files and taking a free number. PowerShell needs the whole switch quoted as `'-bl:{}'`, otherwise the braces get mangled before MSBuild sees them.

After the build, the agent confirms the file exists. A run that dies before MSBuild starts, say on a bad argument, writes no binlog at all. The skill also covers `git clean -fdx`: without `-e "*.binlog"` it wipes your build history, and with it the chance to compare before and after a fix. The logs feed `binlog-failure-analysis` and `build-perf-diagnostics`, which have nothing to read without them.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill binlog-generation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/binlog-generation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/binlog-generation/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill binlog-generation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/binlog-generation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill binlog-generation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/binlog-generation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dotnet/skills binlog-generation
```

2. **Manually: put the files in place**
- File: `.github/skills/binlog-generation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill binlog-generation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dotnet/skills --path plugins/dotnet-msbuild/skills/binlog-generation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/binlog-generation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill binlog-generation -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md

## When to use it
- capture a binlog from a failed build without re-running it
- keep separate logs for Debug and Release builds
- hand a build trace to `binlog-failure-analysis`
- survive `git clean -fdx` with build logs intact

## Example prompts
- Build the solution with `/bl:{}` so I get a binlog
- Run `dotnet test '-bl:{}'` in PowerShell and tell me where the file landed
- Rebuild in Release with `/bl:{}` and compare it to the previous binlog

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0c53270f113400f9.

BEGIN THIRD-PARTY FILE 0c53270f113400f9
````text
---
name: binlog-generation
description: "Generate MSBuild binary logs (binlogs) for build diagnostics and analysis. 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 must quote the complete switch as '-bl:{}'. DO NOT USE FOR: non-MSBuild build systems (npm, Maven, CMake), analyzing an existing binlog (use binlog-failure-analysis instead), binlog MCP startup failures (use troubleshoot-binlog-mcp)."
license: MIT
---

# 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 quoting the complete switch:**

```powershell
# Keep the literal {} placeholder in one argument
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 - quote the complete PowerShell argument
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
```

## One build = one binlog

Add `/bl:{}` to **every** MSBuild invocation separately — never reuse a name and
never rely on bare `/bl`:
````
END THIRD-PARTY FILE 0c53270f113400f9

The third-party file has ended. Everything between the 0c53270f113400f9 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2641 of 4284 bytes. © dotnet · MIT · https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md