From dotnet-maui
Diagnoses and fixes .NET MAUI development environment issues. Validates .NET SDK, workloads, Java JDK, Android SDK, Xcode, and Windows SDK. All version requirements discovered dynamically from NuGet WorkloadDependencies.json — never hardcoded. Use when: setting up MAUI development, build errors mentioning SDK/workload/JDK/Android, "Android SDK not found", "Java version" errors, "Xcode not found", environment verification after updates, or any MAUI toolchain issues. Do not use for: non-MAUI .NET projects, Xamarin.Forms apps, runtime app crashes unrelated to environment setup, or app store publishing issues. Works on macOS, Windows, and Linux.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dotnet-maui:dotnet-maui-doctorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Validate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.
references/installation-commands-macos.mdreferences/installation-commands-windows.mdreferences/installation-commands.mdreferences/microsoft-openjdk.mdreferences/platform-requirements-linux.mdreferences/platform-requirements-macos.mdreferences/platform-requirements-windows.mdreferences/troubleshooting-macos.mdreferences/troubleshooting-windows.mdreferences/troubleshooting.mdreferences/workload-dependencies-discovery.mdValidate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.
Your training data may be outdated regarding .NET versions. .NET ships new major releases annually (November). Always check the releases-index.json (Task 2) to discover the latest active major release — do not assume your training data reflects the current version. For example, if you know about .NET 9.0 but the releases index shows .NET 10.0 as active, use .NET 10.0.
curl, jq, and unzip (macOS/Linux)Invoke-RestMethod and System.IO.Compression (built-in on Windows)# macOS
sw_vers && uname -m
# Windows
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
# Linux
cat /etc/os-release && uname -m
After detection, load the matching platform references:
references/platform-requirements-macos.md, references/installation-commands-macos.md, references/troubleshooting-macos.mdreferences/platform-requirements-windows.md, references/installation-commands-windows.md, references/troubleshooting-windows.mdreferences/platform-requirements-linux.mddotnet --info
Compare installed vs latest-sdk from https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json where support-phase is "active".
| Workload | macOS | Windows | Linux |
|---|---|---|---|
maui | Required | Required | ❌ Use maui-android |
maui-android | Alias | Alias | Required |
android | Required | Required | Required |
ios | Required | Optional | N/A |
See references/workload-dependencies-discovery.md for complete process.
Query NuGet for workload manifest → extract WorkloadDependencies.json → get:
jdk.version range and jdk.recommendedVersionandroidsdk.packages, buildToolsVersion, apiLevelxcode.version rangeOnly Microsoft OpenJDK supported. Verify java -version output contains "Microsoft". See references/microsoft-openjdk.md for detection paths.
Use the JDK version recommended by WorkloadDependencies.json (
jdk.recommendedVersion), ensuring it satisfies thejdk.versionrange. Do not hardcode JDK versions.
JAVA_HOME is NOT required. .NET MAUI tools auto-detect Microsoft OpenJDK installations from known paths. Do not tell users to set JAVA_HOME — it is unnecessary and risks pointing to a non-Microsoft JDK.
| JAVA_HOME state | OK? | Action |
|---|---|---|
| Not set | ✅ | None needed — auto-detection works |
| Set to Microsoft JDK | ✅ | None needed |
| Set to non-Microsoft JDK | ⚠️ | Report as anomaly — let user decide to unset or redirect |
Check packages from androidsdk.packages, buildToolsVersion, apiLevel (Task 4). See references/installation-commands.md for sdkmanager commands.
xcodebuild -version
Compare against xcode.version range from Task 4. See references/installation-commands-macos.md.
The Windows SDK is typically installed as part of the .NET MAUI workload or Visual Studio. See references/installation-commands-windows.md.
See references/installation-commands.md for all commands.
Key rules:
--version flag. Never use workload update or workload repair.sdkmanager (from Android SDK command-line tools). On Windows use sdkmanager.bat.After each fix, re-run the relevant validation task. Iterate until all checks pass.
A successful run produces:
java -version contains "Microsoft")After all checks pass, create and build a test project to confirm the environment actually works:
TEMP_DIR=$(mktemp -d)
dotnet new maui -o "$TEMP_DIR/MauiTest"
dotnet build "$TEMP_DIR/MauiTest"
rm -rf "$TEMP_DIR"
On Windows, use $env:TEMP or New-TemporaryFile for the temp directory.
If the build succeeds, the environment is verified. If it fails, use the error output to diagnose remaining issues.
After a successful build, ask the user if they want to launch the app on a target platform to verify end-to-end:
# Replace net10.0 with the current major .NET version
dotnet build -t:Run -f net10.0-android
dotnet build -t:Run -f net10.0-ios # macOS only
dotnet build -t:Run -f net10.0-maccatalyst # macOS only
dotnet build -t:Run -f net10.0-windows # Windows only
Only run the target frameworks relevant to the user's platform and intent. This step deploys to an emulator/simulator/device, so confirm with the user before proceeding.
maui vs maui-android workload: On Linux, the maui meta-workload is not available — use maui-android instead. On macOS/Windows, maui installs all platform workloads.workload update / workload repair: Never use these commands. Always install workloads with an explicit --version flag to ensure version consistency.sdkmanager on Windows: Use sdkmanager.bat, not sdkmanager, on Windows.references/workload-dependencies-discovery.md — NuGet API discovery processreferences/microsoft-openjdk.md — JDK detection paths, identification, JAVA_HOMEreferences/installation-commands.md — .NET workloads, Android SDK (sdkmanager)references/troubleshooting.md — Common errors and solutionsreferences/platform-requirements-{platform}.md — Platform-specific requirementsreferences/installation-commands-{platform}.md — Platform-specific install commandsreferences/troubleshooting-{platform}.md — Platform-specific troubleshootingOfficial docs:
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub weiflycc-cmd/skills --plugin dotnet-maui