# How the dotnet-diag Plugin Streamlines .NET Performance Investigations

> Streamline .NET performance investigations with the dotnet-diag plugin. Automate analysis, trace collection, and dump capture to diagnose application bottlenecks efficiently.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: how-to-guide
- Published: 2026-07-06

---

**The dotnet-diag plugin provides a modular collection of skills and an orchestrating agent that automate source-code analysis, performance trace collection, and crash dump capture to diagnose bottlenecks in .NET applications.**

The `dotnet-diag` plugin in the `dotnet/skills` repository offers a structured approach to performance troubleshooting by packaging diagnostic expertise into reusable, executable workflows. Unlike generic profiling tools, this plugin embeds domain-specific knowledge for .NET runtime environments, enabling developers to identify anti-patterns and collect actionable diagnostics without leaving their development context.

## Architecture of the dotnet-diag Plugin

The plugin follows the Agent Skills standard architecture, separating metadata, individual capabilities, and high-level orchestration into distinct layers.

### Plugin Metadata and Manifest

At the root of the plugin, [`plugins/dotnet-diag/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/plugin.json) declares the bundle metadata, including version, description, and directory pointers. This manifest registers the `skills/` and `agents/` directories, allowing the host system to discover available diagnostic capabilities dynamically.

### Skill-Based Investigation Workflow

Each skill operates as a self-contained unit with a dedicated markdown file and optional reference materials. The implementation remains lightweight: skills perform file scans, present interactive checklists, and defer to external tools like **PerfView** or **dotnet-trace** for heavyweight data capture. Reference files (e.g., [`references/critical-patterns.md`](https://github.com/dotnet/skills/blob/main/references/critical-patterns.md)) store concrete `grep` recipes and platform-specific command-line examples.

## Core Performance Investigation Skills

The plugin ships with three primary skills targeting distinct investigation phases.

### Analyzing Source Code Anti-Patterns

The `analyzing-dotnet-performance` skill, defined in [`plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md), scans repositories for approximately 50 known performance anti-patterns. It detects issues such as async misuse, excessive allocations, and LINQ queries on hot paths, then emits prioritized findings with concrete remediation steps. This static analysis runs entirely on source code before any runtime instrumentation occurs.

### Collecting Performance Traces

The `dotnet-trace-collect` skill guides users through tool selection and configuration based on environment constraints. Defined in [`plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md), it loads reference documentation (such as [`references/perfview.md`](https://github.com/dotnet/skills/blob/main/references/perfview.md)) to generate exact command syntax for the selected tool. The skill considers factors including operating system, container deployment, administrative privileges, and symptom type (e.g., high CPU or memory pressure) to recommend the appropriate collector.

### Capturing Crash Dumps

For post-mortem analysis, the `dump-collect` skill provides platform-specific instructions for enabling and capturing crash dumps. Located at [`plugins/dotnet-diag/skills/dump-collect/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/skills/dump-collect/SKILL.md), it supports modern .NET runtimes including CoreCLR and NativeAOT across Windows, Linux, and macOS. The skill automatically detects runtime types and invokes the correct workflow from reference files like [`references/coreclr-dumps.md`](https://github.com/dotnet/skills/blob/main/references/coreclr-dumps.md), handling container scenarios and permission requirements.

## Orchestrating Investigations with the Performance Agent

The optional agent defined in [`plugins/dotnet-diag/agents/optimizing-dotnet-performance.agent.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/agents/optimizing-dotnet-performance.agent.md) strings the three skills into a cohesive workflow: *code-pattern analysis → trace collection (if needed) → dump collection (if needed) → recommendations*. This agent can be invoked from chat-style interfaces to process a single "optimize my app" command, automatically routing between static analysis and dynamic data collection based on preliminary findings.

## Practical Usage Examples

Install a specific performance skill using the skill installer:

```bash
skill-installer install https://github.com/dotnet/skills/tree/main/plugins/dotnet-diag/skills/analyzing-dotnet-performance

```

Run the performance-analysis skill on a repository to scan for anti-patterns:

```bash
skill-run analyzing-dotnet-performance \
  --source ./MyApp \
  --hot-paths Controllers/HomeController.cs \
  --framework net8.0 \
  --scan-depth comprehensive

```

Collect a trace for a production environment with high CPU symptoms on Windows:

```bash
skill-run dotnet-trace-collect \
  --symptom "high CPU" \
  --runtime net8.0 \
  --os windows \
  --deployment non-container \
  --admin true

```

The skill selects PerfView, loads [`plugins/dotnet-diag/skills/dotnet-trace-collect/references/perfview.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/skills/dotnet-trace-collect/references/perfview.md), and outputs the exact command to execute (e.g., `PerfView collect /ThreadTime …`).

Capture a crash dump on Linux for a CoreCLR application:

```bash
skill-run dump-collect \
  --platform linux \
  --runtime coreclr \
  --process-name myservice \
  --output /var/dumps

```

This executes the appropriate `strings` detection logic and invokes the `dotnet-dump collect` workflow described in the plugin's CoreCLR dumps reference.

## Extending the Plugin

Because the plugin adheres to the Agent Skills schema, adding new diagnostic capabilities requires only creating a new subdirectory under `skills/` and updating the `skills` array in [`plugins/dotnet-diag/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/plugin.json). The optimizing agent automatically discovers and exposes new skills without requiring modifications to its own logic, enabling community contributions for specialized scenarios like BenchmarkDotNet integration or memory leak detection.

## Summary

- The **dotnet-diag plugin** provides structured, code-driven workflows for .NET performance investigations within the `dotnet/skills` ecosystem.
- Three core skills handle **static analysis** (`analyzing-dotnet-performance`), **trace collection** (`dotnet-trace-collect`), and **dump capture** (`dump-collect`).
- An optional **agent** orchestrates these skills into a unified optimization pipeline.
- The plugin leverages **reference markdown files** to store platform-specific commands and detection patterns, keeping the skill logic lightweight.
- **Extensibility** is built into the architecture via the [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest and standard directory conventions.

## Frequently Asked Questions

### What tools does the dotnet-diag plugin support for trace collection?

The plugin supports multiple industry-standard tools including **PerfView**, **dotnet-trace**, and **dotnet-monitor**. The `dotnet-trace-collect` skill selects the appropriate tool based on runtime environment variables such as operating system, container deployment status, and administrative privileges, then generates the exact command syntax needed for execution.

### How does the analyzing-dotnet-performance skill detect performance issues?

This skill scans source code for approximately 50 documented anti-patterns including improper async/await usage, excessive object allocations, and LINQ operations on hot execution paths. It implements detection logic defined in [`plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md) and references files like [`references/critical-patterns.md`](https://github.com/dotnet/skills/blob/main/references/critical-patterns.md), categorizing findings by severity and providing specific remediation code.

### Can the dotnet-diag plugin be used in containerized environments?

Yes. The `dump-collect` skill explicitly includes container scenarios in its logic, detecting when a process runs inside a container and adjusting dump collection commands accordingly. The `dotnet-trace-collect` skill also accepts a `--deployment` parameter to distinguish between container and non-container deployments, ensuring the generated commands mount necessary volumes and handle process identification correctly.

### How do I add a new performance skill to the dotnet-diag plugin?

Create a new subdirectory under `plugins/dotnet-diag/skills/` containing a [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file and any required reference files. Update the `skills` array in [`plugins/dotnet-diag/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-diag/plugin.json) to include the new skill path. The existing `optimizing-dotnet-performance` agent will automatically discover and incorporate the new capability into its available workflow steps.