# How to Report a Bug in dotnet/skills: A Complete Guide > Learn how to report a bug in dotnet/skills by opening a GitHub issue with a reproducible example and environment details. Follow this guide for effective bug reporting. - Repository: [.NET Platform/skills](https://github.com/dotnet/skills) - Tags: how-to-guide - Published: 2026-07-08 --- **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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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//skills//` and contain task-focused instructions - **Agents** are defined at `plugins//agents/.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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/skills/run-tests/SKILL.md) - **Environment**: Specify OS, .NET SDK version (from [`global.json`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md)**: Contains the official guidelines for submitting bugs and the recommended issue format - **[`README.md`](https://github.com/dotnet/skills/blob/main/README.md)**: Provides repository overview and installation instructions - **`plugins//skills//SKILL.md`**: The source implementation of the specific skill exhibiting the bug - **[`eng/skill-validator/src/README.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/global.json)**: Specifies the .NET SDK version used by the repository ## Example Bug Report Template Use this markdown skeleton when drafting your issue: ```markdown **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`](https://github.com/dotnet/skills/blob/main/SKILL.md) files or agent configurations to help maintainers locate the source - **Provide environment details** from [`global.json`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/SKILL.md) snippet, a minimal project file that triggers the behavior, and exact steps to reproduce. According to [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/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//agents/.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.