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

Use the built-in skill-validator tool to statically check plugin.json manifests and 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) – 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:

# 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 and utilizes 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 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:

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. 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 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:

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 to attach to the running process:

{
  "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 exits with code 0 only when all checks pass.

2. Inspect the offending manifest – Open the reported plugin.json and verify required fields. The schema validation logic resides in eng/skill-validator/src/Check/PluginProfiler.cs.

3. Validate skill markdown – Check the front-matter and input tables in the specific 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 output for missing NuGet packages like Microsoft.Testing.Extensions.TrxReport. Add missing dependencies to the plugin's plugin.json under externalDependencies or to a local Directory.Packages.props.

8. Log the environment – Check the validator logs for SDK version, 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 schema invalid – Missing required fields (name, description). Add them according to the schema in PluginProfiler.cs.
• "Agent not registered" – The agent file is not listed in the agents array within 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 and SKILL.md files.
• Reference eng/skill-validator/src/Check/PluginProfiler.cs for manifest schema requirements and 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 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 file for the specific skill—such as 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 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.

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