How the dotnet-diag Plugin Streamlines .NET Performance Investigations

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 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) 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, 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, it loads reference documentation (such as 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, 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, 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 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:

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:

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:

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, and outputs the exact command to execute (e.g., PerfView collect /ThreadTime …).

Capture a crash dump on Linux for a CoreCLR application:

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. 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 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 and references files like 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 file and any required reference files. Update the skills array in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}