.NET MAUI Doctor Skill #33757

Redth · 2026-01-29T01:30:55Z

This pull request introduces initial support for a .NET MAUI-focused plugin, including marketplace and plugin definitions, as well as comprehensive documentation for two specialized skills: workload discovery and environment diagnosis. The documentation emphasizes dynamic discovery of all version and dependency requirements from authoritative NuGet APIs, ensuring up-to-date and platform-specific guidance for .NET MAUI development.

Workload Discovery Skill Documentation

Added .claude/skills/dotnet-workload-info/SKILL.md, providing detailed instructions and workflow for dynamically discovering .NET SDK, workload, and dependency versions from live NuGet APIs, including output formats and error handling.
Added .claude/skills/dotnet-workload-info/references/workload-discovery-process.md, a deep reference covering NuGet API usage, package conventions, version conversions, and a complete example for workload discovery.

MAUI Doctor Skill Documentation

Added .claude/skills/maui-doctor/SKILL.md, documenting an environment diagnostic skill that validates and remediates .NET MAUI development setups across macOS, Windows, and Linux, always using live NuGet data for requirements.
Added .claude/skills/maui-doctor/references/platform-requirements.md, summarizing platform-specific requirements for .NET MAUI development, with all version requirements to be discovered dynamically via workload manifests.

Plugin and Marketplace Definitions

Added .claude-plugin/marketplace.json and .claude-plugin/plugin.json to register the dotnet-maui-skills plugin in the marketplace, specifying its focus on .NET MAUI development and referencing Microsoft as the owner. [1] [2]

This is an example and we may not necessarily add a marketplace and plugin manifest here directly.

Introduces the env-setup agent for validating and fixing .NET MAUI development environments, including SDK, workloads, Android SDK, Java JDK, and Xcode checks. Updates copilot-instructions with env-setup agent details and trigger phrases. Adds a prompt for running a full MAUI environment health check. Updates .vscode/mcp.json to configure mauidevenv and appledev servers.

Introduces the dotnet-maui-skills plugin with marketplace and plugin metadata, and adds detailed documentation for two skills: dotnet-workload-info and maui-doctor. Includes comprehensive references for workload discovery, installation commands, Microsoft OpenJDK, platform requirements, and troubleshooting. Also updates .config/dotnet-tools.json and removes an obsolete agent setup guide.

References to the env-setup agent and its trigger phrases have been removed from the copilot-instructions.md file. This likely reflects deprecation or removal of the agent from the repository.

Deleted the .github/prompts/maui-check.prompt.md and .vscode/mcp.json files as they are no longer needed for the project setup or development environment.

.claude/skills/dotnet-workload-info/references/workload-discovery-process.md

Update documentation and installation instructions to recommend Microsoft OpenJDK 21 instead of 17 for .NET MAUI development. This is a temporary workaround until WorkloadDependencies.json is updated in a future Android workload release. All relevant references, commands, and troubleshooting steps now reflect JDK 21 as the recommended version.

Looking at alternative approaches still.

Copilot

Pull request overview

This PR introduces comprehensive documentation for two .NET MAUI-focused skills: workload discovery and environment diagnosis (MAUI Doctor). The documentation emphasizes dynamic discovery of version requirements from authoritative NuGet APIs rather than hardcoding values, ensuring up-to-date and platform-specific guidance.

Changes:

Added MAUI Doctor skill documentation with platform-specific requirements, troubleshooting guides, installation commands, and Microsoft OpenJDK requirements
Added dotnet-workload-info skill documentation for discovering .NET SDK versions, workload sets, and dependency requirements from live NuGet APIs
Added example plugin and marketplace definition files (noted as potentially not permanent)

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
`.claude/skills/maui-doctor/references/workload-dependencies-discovery.md`	Documents the NuGet API discovery process for workload dependencies including JDK, Android SDK, and Xcode requirements
`.claude/skills/maui-doctor/references/troubleshooting.md`	Comprehensive troubleshooting guide for .NET SDK, JDK, Android SDK, Xcode, and build errors
`.claude/skills/maui-doctor/references/platform-requirements.md`	Platform-specific requirements summary for macOS, Windows, and Linux
`.claude/skills/maui-doctor/references/microsoft-openjdk.md`	Detailed Microsoft OpenJDK requirements, installation paths, detection scripts, and troubleshooting
`.claude/skills/maui-doctor/references/installation-commands.md`	Complete installation command reference for all MAUI development dependencies across platforms
`.claude/skills/maui-doctor/SKILL.md`	Main skill definition for the MAUI Doctor diagnostic and remediation tool
`.claude/skills/dotnet-workload-info/references/workload-discovery-process.md`	Detailed NuGet API reference and package structure documentation
`.claude/skills/dotnet-workload-info/SKILL.md`	Skill definition for workload information discovery from NuGet APIs

Copilot · 2026-01-29T19:00:41Z

.claude/skills/maui-doctor/references/troubleshooting.md

+export PATH="$PATH:$HOME/.dotnet"
+
+# Or install SDK
+curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 10.0


The bash script syntax "bash /dev/stdin" is non-standard. The typical syntax is "bash -s" or just piping to "bash". While it may work, "bash /dev/stdin" is less portable and could fail on some systems. Change to the more standard form: "curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0"

Suggested change

curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 10.0

curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0

Copilot · 2026-01-29T19:00:41Z

.claude/skills/maui-doctor/references/installation-commands.md

+curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel LTS
+
+# Install specific channel (replace MAJOR.MINOR with actual version)
+curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel $DOTNET_CHANNEL
+
+# Install specific version (replace with actual version from releases-index.json)
+curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version $SDK_VERSION
+
+# Add to PATH (add to ~/.bashrc or ~/.zshrc)
+export PATH="$PATH:$HOME/.dotnet"
+export DOTNET_ROOT="$HOME/.dotnet"
+```
+
+### Windows
+
+```powershell
+# Using winget (replace X with major version)
+winget install Microsoft.DotNet.SDK.$DOTNET_MAJOR
+
+# Using PowerShell script
+Invoke-WebRequest -Uri https://dot.net/v1/dotnet-install.ps1 -OutFile dotnet-install.ps1
+./dotnet-install.ps1 -Channel $DOTNET_CHANNEL
+```
+
+### Homebrew (macOS)
+
+```bash
+brew install --cask dotnet-sdk
+```


The same "bash /dev/stdin" syntax issue appears in multiple locations throughout this file. All instances should use the standard "bash -s --" syntax instead. This affects lines 20, 30, 36, 58, 476, 577.

Copilot · 2026-01-29T19:00:42Z

.claude/skills/maui-doctor/references/installation-commands.md

+### Install MAUI Workloads
+
+**Always use explicit workload set version** to ensure consistent, reproducible installs.
+
+First, find the latest workload set version using the process in `workload-dependencies-discovery.md`:
+```bash
+# Query NuGet for latest workload set
+# SDK band = first 2 segments of SDK version (e.g., 10.0 from 10.0.102)
+curl -s "https://azuresearch-usnc.nuget.org/query?q=Microsoft.NET.Workloads.$SDK_BAND&prerelease=false" | \
+  jq '.data[] | select(.id | test("^Microsoft.NET.Workloads.$SDK_BAND.[0-9]+$")) | {id, version}'
+
+# Convert NuGet version to CLI version:
+# NuGet A.B.C → CLI A.0.B (e.g., NuGet 10.102.0 → CLI 10.0.102)
+```
+
+Then install with explicit version:
+```bash
+# Full MAUI installation (recommended)
+dotnet workload install maui --version $WORKLOAD_VERSION
+
+# Individual workloads
+dotnet workload install android --version $WORKLOAD_VERSION
+dotnet workload install ios --version $WORKLOAD_VERSION           # macOS only meaningful
+dotnet workload install maccatalyst --version $WORKLOAD_VERSION   # macOS only meaningful
+
+# Multiple at once
+dotnet workload install maui android ios maccatalyst --version $WORKLOAD_VERSION
+```


The installation command syntax uses placeholder variables (e.g., $WORKLOAD_VERSION, $BUILD_TOOLS_VERSION) without defining how users should set them or showing where these values come from. While the note at line 19-22 mentions discovering versions, it would be clearer to show a concrete example first, then explain the placeholders, rather than showing placeholders throughout without concrete examples.

Copilot · 2026-01-29T19:00:42Z

.claude/skills/maui-doctor/references/workload-dependencies-discovery.md

+**Version conversion**: NuGet `10.102.0` → CLI `10.0.102`
+```
+parts = nugetVersion.split('.')
+cliVersion = parts[0] + ".0." + parts[1]
+```


The version conversion formula shown here is inconsistent with the explanation in other files. The comment says "NuGet 10.102.0 → CLI 10.0.102" but the code shows "parts[0] + '.0.' + parts[1]" which would convert 10.102.0 to 10.0.102 correctly. However, this doesn't work for all cases since it only swaps segments. Consider clarifying that this specific conversion works when the NuGet version has format {major}.{patch}.{build} and produces CLI version {major}.0.{patch}.

Copilot · 2026-01-29T19:00:42Z

.claude/skills/dotnet-workload-info/SKILL.md

+
+Filter: Match `Microsoft.NET.Workloads.{major}.{band}`, exclude `.Msi.*`, pick highest version.
+
+**Version conversion**: NuGet `10.102.0` → CLI `10.0.102` (swap middle segments)


The version conversion explanation "swap middle segments" is imprecise. The conversion from NuGet version "10.102.0" to CLI version "10.0.102" isn't simply swapping middle segments - it's inserting a ".0" and rearranging. The actual transformation is: take first segment, append ".0.", then append second segment. Consider using the more precise formula shown in workload-dependencies-discovery.md: parts[0] + ".0." + parts[1]

Suggested change

**Version conversion**: NuGet `10.102.0` → CLI `10.0.102` (swap middle segments)

**Version conversion**: NuGet `10.102.0` → CLI `10.0.102` (CLI = `parts[0] + ".0." + parts[1]`, i.e., NuGet `major.band.patch` → CLI `major.0.band`)

Copilot · 2026-01-29T19:00:44Z

.claude/skills/maui-doctor/references/installation-commands.md

+  echo "ERROR: Set WORKLOAD_VERSION before running"
+  exit 1
+fi
+


The Linux setup script also lacks validation for BUILD_TOOLS_VERSION and API_LEVEL variables, despite checking WORKLOAD_VERSION. These variables are used in critical installation commands later in the script and will cause failures if empty.

Suggested change

if [ -z "$BUILD_TOOLS_VERSION" ]; then

echo "ERROR: Set BUILD_TOOLS_VERSION before running"

exit 1

fi

if [ -z "$API_LEVEL" ]; then

echo "ERROR: Set API_LEVEL before running"

exit 1

fi

Copilot · 2026-01-29T19:00:44Z

.claude/skills/maui-doctor/references/platform-requirements.md

@@ -0,0 +1,171 @@
+# Platform Requirements for .NET MAUI
+
+Platform-specific requirements for .NET MAUI development. **All specific versions must be discovered from WorkloadDependencies.json** - see `workload-dependencies-discovery.md`.


The description states "All specific versions must be discovered from WorkloadDependencies.json" but this creates a circular dependency problem. To discover the WorkloadDependencies.json, you first need to know which version to download. The documentation should clarify that the SDK version and workload set version are discovered first through the releases-index.json and NuGet search APIs, and only then can you obtain the WorkloadDependencies.json for tool version requirements.

Suggested change

Platform-specific requirements for .NET MAUI development. **All specific versions must be discovered from WorkloadDependencies.json** - see `workload-dependencies-discovery.md`.

Platform-specific requirements for .NET MAUI development. **Discover the .NET SDK and workload set versions via `releases-index.json` and NuGet search APIs, then obtain the corresponding `WorkloadDependencies.json` to determine specific tool and platform version requirements** - see `workload-dependencies-discovery.md`.

Copilot · 2026-01-29T19:00:45Z

.claude/skills/maui-doctor/references/microsoft-openjdk.md

+# Session only
+$env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-17.0.14+7"
+
+# Permanent (requires admin)


In the Windows PowerShell example, the permanent environment variable setting uses "Machine" scope which requires admin rights. The comment says "requires admin" but the command should be wrapped in a check or preceded by a clearer warning. Consider adding: "# Requires Administrator PowerShell" on the line immediately before the command.

Suggested change

# Permanent (requires admin)

# Permanent (requires admin)

# Requires Administrator PowerShell

Copilot · 2026-01-29T19:00:45Z

.claude/skills/dotnet-workload-info/SKILL.md

+Filter: Match `Microsoft.NET.Workloads.{major}.{band}`, exclude `.Msi.*`, pick highest version.
+


The workload set package naming convention shows packages like "Microsoft.NET.Workloads.10.0.100" but the example shows searching with "Microsoft.NET.Workloads.10.0" (without the band). While this works for the search, it might confuse readers. Consider clarifying that the search term is intentionally broader to find all band variants, then filtered to the specific band.

Suggested change

Filter: Match `Microsoft.NET.Workloads.{major}.{band}`, exclude `.Msi.*`, pick highest version.

This query intentionally searches for `Microsoft.NET.Workloads.{MAJOR}.0` (without the band digit) so that all band variants (for example, `Microsoft.NET.Workloads.10.0.100`, `Microsoft.NET.Workloads.10.0.200`) are returned in a single call.

Filter: From those results, select packages whose ID starts with `Microsoft.NET.Workloads.{band}`, exclude `.Msi.*`, then pick the highest version.

Copilot · 2026-01-29T19:00:45Z

.claude/skills/dotnet-workload-info/SKILL.md

+```bash
+curl -o workloadset.nupkg "https://api.nuget.org/v3-flatcontainer/microsoft.net.workloads.{band}/{version}/microsoft.net.workloads.{band}.{version}.nupkg"
+unzip -p workloadset.nupkg data/microsoft.net.workloads.workloadset.json
+```


The curl command for downloading the workload set uses curly brace placeholders "{band}" and "{version}" which won't be expanded by the shell. These should be either: 1) replaced with actual example values, 2) changed to shell variable syntax ($band, $version), or 3) clearly marked as placeholders requiring manual substitution. The same issue appears in the Step 4 curl command.

Redth added 5 commits January 8, 2026 16:40

Remove env-setup agent documentation

1f5a07b

References to the env-setup agent and its trigger phrases have been removed from the copilot-instructions.md file. This likely reflects deprecation or removal of the agent from the repository.

Remove MAUI check prompt and VSCode MCP config

e9b3603

Deleted the .github/prompts/maui-check.prompt.md and .vscode/mcp.json files as they are no longer needed for the project setup or development environment.

Revert appledev.tools and VSCode mcp.json changes

8849603

rmarinho reviewed Jan 29, 2026

View reviewed changes

.claude/skills/dotnet-workload-info/references/workload-discovery-process.md Show resolved Hide resolved

Redth added 2 commits January 29, 2026 10:11

Remove marketplace poc manifests

a762f3f

Looking at alternative approaches still.

Redth marked this pull request as ready for review January 29, 2026 18:55

Copilot AI review requested due to automatic review settings January 29, 2026 18:55

Copilot started reviewing on behalf of Redth January 29, 2026 18:56 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.NET MAUI Doctor Skill #33757

.NET MAUI Doctor Skill #33757

Uh oh!

Redth commented Jan 29, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	curl -sSL https://dot.net/v1/dotnet-install.sh \| bash /dev/stdin --channel 10.0
	curl -sSL https://dot.net/v1/dotnet-install.sh \| bash -s -- --channel 10.0


		Filter: Match `Microsoft.NET.Workloads.{major}.{band}`, exclude `.Msi.*`, pick highest version.

		Version conversion: NuGet `10.102.0` → CLI `10.0.102` (swap middle segments)

+if [ -z "$BUILD_TOOLS_VERSION" ]; then
+  echo "ERROR: Set BUILD_TOOLS_VERSION before running"
+  exit 1
+fi
+if [ -z "$API_LEVEL" ]; then
+  echo "ERROR: Set API_LEVEL before running"
+  exit 1
+fi

		@@ -0,0 +1,171 @@
		# Platform Requirements for .NET MAUI

		Platform-specific requirements for .NET MAUI development. All specific versions must be discovered from WorkloadDependencies.json - see `workload-dependencies-discovery.md`.

	# Permanent (requires admin)
	# Permanent (requires admin)
	# Requires Administrator PowerShell

-Filter: Match `Microsoft.NET.Workloads.{major}.{band}`, exclude `.Msi.*`, pick highest version.
+This query intentionally searches for `Microsoft.NET.Workloads.{MAJOR}.0` (without the band digit) so that all band variants (for example, `Microsoft.NET.Workloads.10.0.100`, `Microsoft.NET.Workloads.10.0.200`) are returned in a single call.
+Filter: From those results, select packages whose ID starts with `Microsoft.NET.Workloads.{band}`, exclude `.Msi.*`, then pick the highest version.

.NET MAUI Doctor Skill #33757

Are you sure you want to change the base?

.NET MAUI Doctor Skill #33757

Uh oh!

Conversation

Redth commented Jan 29, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants