How to Report a Bug in dotnet/skills: A Complete Guide

To report a bug in dotnet/skills, open a GitHub issue with a minimal reproducible example that identifies the specific plugin or skill path, and include environment details from your global.json and the skill-validator version.

The dotnet/skills repository organizes automation logic into plugins containing skills (task-focused instruction packs) and agents (role-based configurations). When you encounter incorrect guidance from a skill, unexpected agent behavior, or failures in the skill-validator engine, submitting a detailed bug report ensures maintainers can triage and fix the issue efficiently. Following the standards defined in CONTRIBUTING.md helps you report a bug in dotnet/skills with the technical precision the project requires.

Understand the Repository Structure Before Reporting

Before filing an issue, identify exactly which component contains the bug. The repository uses a strict organizational pattern:

• Skills reside at plugins/<plugin>/skills/<skill>/ and contain task-focused instructions
• Agents are defined at plugins/<plugin>/agents/<agent>.agent.md as role-based configurations
• The skill-validator engine at eng/skill-validator/src/ runs automated tests against these assets

Knowing the specific file path—such as plugins/dotnet-test/skills/run-tests/SKILL.md—allows you to include precise permalinks in your bug report, enabling maintainers to locate the source code instantly.

Step-by-Step Guide to Report a Bug in dotnet/skills

Prepare a Minimal Reproducible Example

Create a small, self-contained sample that demonstrates the failure. Include only the files necessary to reproduce the bug, such as:

• A minimal SKILL.md snippet from the affected skill
• A condensed test fixture or project file
• Exact command sequences that trigger the error

According to CONTRIBUTING.md, the maintainers emphasize issues that describe the "user problem, the proposed outcome, and a small example of the desired behavior."

Open a New GitHub Issue

Navigate to the Issues tab of the repository at https://github.com/dotnet/skills/issues and click New issue. Select the Bug report template if available; otherwise, use a blank issue formatted according to the repository's conventions.

Complete the Bug Report Template

Structure your issue with these specific sections to ensure comprehensive coverage:

• Title: Use a concise description like "dotnet-test skill mis-detects flaky tests on CI"
• Description: Provide a one-paragraph overview of the problem
• Steps to Reproduce: List exact commands or UI actions, including setup requirements like dotnet build version or OS specifics
• Expected Behaviour: Describe what you anticipated should happen
• Actual Behaviour: Detail what you observed, including error messages or incorrect output
• Relevant Files: Include GitHub permalinks to specific files like plugins/dotnet-test/skills/run-tests/SKILL.md
• Environment: Specify OS, .NET SDK version (from global.json), and tool versions (skill-validator, dotnet, etc.)
• Additional Context: Link to related GitHub issues or external documentation

Label and Submit Your Issue

Add the bug label to categorize the issue. If you know which plugin is affected, include the plugin name as a label (e.g., dotnet-test) to route the report to the correct code owners listed in .github/CODEOWNERS. After submission, be prepared to answer follow-up questions and provide additional logs if requested by the maintainers.

Key Files to Reference in Your Bug Report

When investigating or describing bugs, reference these critical files:

• CONTRIBUTING.md: Contains the official guidelines for submitting bugs and the recommended issue format
• README.md: Provides repository overview and installation instructions
• plugins/<plugin>/skills/<skill>/SKILL.md: The source implementation of the specific skill exhibiting the bug
• eng/skill-validator/src/README.md: Documentation for the validator engine used in automated testing
• .github/CODEOWNERS: Defines which maintainers are automatically assigned to review specific issues
• global.json: Specifies the .NET SDK version used by the repository

Example Bug Report Template

Use this markdown skeleton when drafting your issue:

**Title:** dotnet-test skill reports "No tests found" on macOS 12

**Description**
Running the `run-tests` skill on a macOS 12 CI agent fails to discover any tests, even though `dotnet test` works locally.

**Steps to Reproduce**
1. Clone the repo and checkout `main`.
2. Run `dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- evaluate --tests-dir tests/dotnet-test plugins/dotnet-test/skills/run-tests`.
3. Observe the skill's output (see screenshot).

**Expected Behaviour**
The skill should locate and execute the test projects, reporting the usual pass/fail summary.

**Actual Behaviour**
The skill prints `No test is available` and exits with error code 1.

**Relevant Files**
- [plugins/dotnet-test/skills/run-tests/SKILL.md](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/skills/run-tests/SKILL.md)

**Environment**
- OS: macOS 12.6
- .NET SDK: 8.0.200 (from `global.json`)
- Skill-validator version: 0.7.1 (built from `eng/skill-validator/src`)

**Additional Context**
- Same command works on Windows 10 with .NET 8.
- Related issue: #1234 (link to similar failure on Linux).

Summary

• Identify the specific component (skill, agent, or validator) using the repository's plugins/ directory structure before reporting
• Include precise file paths and GitHub permalinks to SKILL.md files or agent configurations to help maintainers locate the source
• Provide environment details from global.json and skill-validator versions, as bugs often manifest only on specific platforms or SDK versions
• Follow the CONTRIBUTING.md guidelines by describing the user problem, proposed outcome, and a minimal reproducible example
• Use appropriate labels and reference .github/CODEOWNERS to ensure the correct maintainers review your bug report

Frequently Asked Questions

Where do I find the code owners for a specific plugin in dotnet/skills?

The .github/CODEOWNERS file in the repository root defines which teams or individuals are automatically assigned to review issues and pull requests for specific paths. When you report a bug in plugins/dotnet-test/, the corresponding owner listed in this file will receive notification automatically.

What information should I include if the bug only appears in the skill-validator?

When reporting bugs in the automated test runner, include the exact command you ran—such as dotnet run --project eng/skill-validator/src/SkillValidator.csproj—along with the full console output and the version of the validator built from eng/skill-validator/src/. Also specify the contents of your global.json to confirm the .NET SDK version in use.

How do I create a minimal reproducible example for a skill bug?

Isolate the issue by creating a small repository or gist containing only the necessary SKILL.md snippet, a minimal project file that triggers the behavior, and exact steps to reproduce. According to CONTRIBUTING.md, your example should clearly demonstrate the user problem, the proposed outcome, and the desired behavior without including extraneous code or configuration.

Should I report bugs in agents differently than bugs in skills?

While the general process remains the same, agent bugs require you to specify the agent configuration file path (e.g., plugins/<plugin>/agents/<agent>.agent.md) rather than skill directories. Agent issues often involve role selection or skill routing logic, so include the specific agent definition and describe how it incorrectly selects or executes underlying skills.

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