# How to Debug Issues Within the Plugins Directory of dotnet/skills: A Complete Guide

> Debug dotnet/skills plugin issues effectively. Use skill-validator, run with --debug, and attach the .NET debugger to pinpoint runtime failures. Streamline your development process.

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

---

**Use the built-in `skill-validator` tool to statically check [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifests and [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) definitions, then run skills with `--debug` verbosity and attach the .NET debugger to generated agent processes to isolate runtime failures.**

Debugging issues within the plugins directory of the `dotnet/skills` repository requires a systematic approach across three architectural layers: the plugin manifest, skill definitions, and agent implementations. The repository provides dedicated validation tooling under `eng/skill-validator/src` to catch schema violations and dependency errors before execution. By combining static analysis with targeted runtime debugging, you can efficiently resolve validation failures, missing inputs, and agent load errors.

## Understanding the Plugins Directory Architecture

The `plugins` folder forms the core of the `dotnet/skills` ecosystem, with each subfolder representing a distinct plugin such as `dotnet-test`, `dotnet-msbuild`, or `dotnet-nuget`. Every plugin consists of three primary components that serve as checkpoints during debugging.

### The Three Layers of a Plugin

1.  **Plugin Manifest ([`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json))** – Defines the plugin name, description, and the complete set of skills and agents it contains.
2.  **Skills (`skills/<skill>/SKILL.md`)** – Markdown files describing behavior, inputs, and rules for a specific capability.
3.  **Agents (`agents/<agent>.agent.md`)** – Optional definitions that implement the skill logic through executable code.

When failures occur—such as a skill failing validation, an agent failing to load, or a missing command—your debugging workflow should isolate which of these three layers contains the defect.

## Validating the Plugin Manifest Layer

Manifest errors typically produce symptoms like "`skill-validator` reports plugin not found" or "invalid plugin schema" messages. These issues originate in the `plugins/<plugin>/plugin.json` file.

To diagnose manifest problems, run the static checker against the specific plugin directory:

```bash

# From the repository root

dotnet skill-validator check --plugin plugins/dotnet-test

```

This command invokes the validation logic in [`eng/skill-validator/src/Check/CheckCommand.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/CheckCommand.cs) and utilizes [`PluginProfiler.cs`](https://github.com/dotnet/skills/blob/main/PluginProfiler.cs) to verify JSON schema compliance. The tool outputs a JSON report pinpointing exact file paths and line numbers where properties like `name` or `description` are missing or malformed. Common fixes include adding missing commas, correcting property names, or ensuring the `agents` array lists all existing [`.agent.md`](https://github.com/dotnet/skills/blob/main/.agent.md) files.

## Debugging Skill Definition Errors

Skill-level issues manifest as missing inputs, rule violations, or "unsupported platform" errors. These problems reside in the markdown definitions located at `plugins/<plugin>/skills/<skill>/SKILL.md`.

To validate a specific skill, use the validator's targeted check command:

```bash
dotnet skill-validator check --skill run-tests

```

Inspect the skill file indicated by the report—for example, [`plugins/dotnet-test/skills/run-tests/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/skills/run-tests/SKILL.md). Verify that the front-matter between the `---` delimiters contains valid `name` and `description` fields. Ensure the **Inputs** table matches the expected schema (referencing lines 41-45 in the file) and that **Critical Rules** do not contain forbidden combinations, such as using `--logger trx` on an MTP (Microsoft Testing Platform) project. For filter syntax issues, consult [`plugins/dotnet-test/skills/filter-syntax/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/skills/filter-syntax/SKILL.md) to build correct expressions for VSTest versus MTP frameworks.

## Troubleshooting Agent Implementation Failures

Agent failures appear as load errors, runtime exceptions, or "agent not registered" messages. These occur in the optional `plugins/<plugin>/agents/<agent>.agent.md` files.

First, verify the agent file exists and that its `manifest` header contains valid name, description, and required tool declarations. If the agent loads but fails at runtime, execute the skill with verbose logging enabled:

```bash
dotnet skill-runner \
    --plugin plugins/dotnet-test \
    --skill run-tests \
    --project ./MySolution.sln \
    --verbosity diagnostic \
    --debug

```

For deeper inspection, attach a debugger to the generated agent process. Many agents are generated as C# projects under `agents/`. Configure VS Code with the following [`launch.json`](https://github.com/dotnet/skills/blob/main/launch.json) to attach to the running process:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Attach",
      "type": "coreclr",
      "request": "attach",
      "processId": "${command:pickProcess}"
    }
  ]
}

```

Start the skill runner, select the agent process when prompted, and step through the code to isolate runtime logic errors.

## Step-by-Step Debug Workflow

Follow this systematic sequence to resolve issues when debugging within the plugins directory:

1.  **Run the static checker** – Execute `dotnet skill-validator check --plugin plugins/<plugin>` to generate a diagnostic report. The validator implementation in [`eng/skill-validator/src/Check/CheckCommand.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/CheckCommand.cs) exits with code `0` only when all checks pass.

2.  **Inspect the offending manifest** – Open the reported [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) and verify required fields. The schema validation logic resides in [`eng/skill-validator/src/Check/PluginProfiler.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/PluginProfiler.cs).

3.  **Validate skill markdown** – Check the front-matter and input tables in the specific [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file flagged by the validator.

4.  **Re-run the validator** – Iterate until the static checker reports no errors.

5.  **Execute in a live session** – Use `dotnet skill-runner` with the `--debug` flag to observe runtime behavior. Set `DOTNET_CLI_TELEMETRY_OPTOUT=1` to reduce noise in output logs.

6.  **Attach a debugger** – Use the VS Code configuration above to attach to the agent process and step through execution.

7.  **Check external dependencies** – Review [`eng/skill-validator/src/Check/ExternalDependencyChecker.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/ExternalDependencyChecker.cs) output for missing NuGet packages like `Microsoft.Testing.Extensions.TrxReport`. Add missing dependencies to the plugin's [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) under `externalDependencies` or to a local `Directory.Packages.props`.

8.  **Log the environment** – Check the validator logs for SDK version, [`global.json`](https://github.com/dotnet/skills/blob/main/global.json) location, and resolved `Directory.Build.props` to diagnose platform-specific bugs, such as differences between SDK 8/9 and SDK 10 MTP argument handling.

## Common Pitfalls and Fixes

-   **"`--report-trx` is unrecognized"** – You are using an MTP flag on a VSTest project. Switch to `--logger trx` for VSTest, or add the `Microsoft.Testing.Extensions.TrxReport` package to enable the MTP flag.
-   **"No test is available"** – Incorrect filter syntax for the detected framework. Use the `filter-syntax` skill to generate the correct expression.
-   **[`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) schema invalid** – Missing required fields (`name`, `description`). Add them according to the schema in [`PluginProfiler.cs`](https://github.com/dotnet/skills/blob/main/PluginProfiler.cs).
-   **"Agent not registered"** – The agent file is not listed in the `agents` array within [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json). Add the entry and re-run the validator.

## Summary

-   Start every debugging session with the `skill-validator` tool to catch static errors in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) and [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) files.
-   Reference [`eng/skill-validator/src/Check/PluginProfiler.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/PluginProfiler.cs) for manifest schema requirements and [`ExternalDependencyChecker.cs`](https://github.com/dotnet/skills/blob/main/ExternalDependencyChecker.cs) for dependency validation.
-   Use `dotnet skill-runner --debug` for runtime diagnostics and attach the VS Code debugger to generated agent processes for step-through analysis.
-   Verify platform-specific command differences between VSTest and MTP frameworks when encountering unrecognized argument errors.

## Frequently Asked Questions

### How do I validate a plugin.json file before running a skill?

Run the command `dotnet skill-validator check --plugin plugins/<plugin-name>` from the repository root. This executes the checks defined in [`eng/skill-validator/src/Check/CheckCommand.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Check/CheckCommand.cs) and reports schema violations, missing fields, or JSON syntax errors with precise file and line references.

### Why does my skill fail with "unsupported platform" errors?

This error typically indicates a mismatch between the command-line arguments generated by the skill and the target testing framework. Check the [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file for the specific skill—such as [`plugins/dotnet-test/skills/run-tests/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/skills/run-tests/SKILL.md)—to ensure you are using VSTest-compatible flags (like `--logger trx`) versus MTP-compatible flags (like `--report-trx`), depending on your project configuration.

### How can I attach a debugger to a failing agent process?

First, ensure the agent file exists at `plugins/<plugin>/agents/<agent>.agent.md` and is registered in the manifest. Then, start the skill with `dotnet skill-runner` using the `--debug` flag. Open the generated agent project in VS Code and use a `.NET Core Attach` configuration targeting `${command:pickProcess}` to select and debug the running agent process.

### What causes "Agent not registered" errors in dotnet/skills?

This occurs when an agent markdown file exists in the `agents/` directory but is not listed in the `agents` array within the plugin's [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest. Open the manifest, add the filename to the agents list, and re-run the validator to confirm the registration is recognized by the tooling.