SkillAgentSearch skills...

dotnet-maui-doctor

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

Install / Use

npx skills add dotnet/skills --skill dotnet-maui-doctor

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

94/100

Category

Marketing

Supported Platforms

Universal

Our assessment of dotnet-maui-doctor

dotnet-maui-doctor scores 94/100 on our quality scale, 107th of 642 Marketing skills we index (top 17%).

Its SKILL.md is 9.3 KB long, well organised into 26 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

With 5,471 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
16/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so dotnet-maui-doctor is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-27. Automated pattern scan on 2026-09-27. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

dotnet-maui-doctor compared with similar skills

All 4 of these similar skills score higher than dotnet-maui-doctor; compare them before choosing.

SkillScoreStarsUpdatedFormat
dotnet-maui-doctor (this skill)by dotnet945.5k53d agoSKILL.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md

Frequently asked questions

How do I install dotnet-maui-doctor?
Run npx skills add dotnet/skills --skill dotnet-maui-doctor. The install tabs above show the steps for each supported agent.
Which AI agents does dotnet-maui-doctor work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is dotnet-maui-doctor safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is dotnet-maui-doctor still maintained?
The repository was last updated about 2 months ago, so dotnet-maui-doctor is actively maintained.

name: dotnet-maui-doctor description: >- 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. license: MIT

.NET MAUI Doctor

Validate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.

When to Use

  • Setting up a new .NET MAUI development environment
  • Build errors mentioning missing SDKs, workloads, JDK, or Android components
  • Errors like "Android SDK not found", "Java version", or "Xcode not found"
  • Verifying environment health after SDK or OS updates

When Not to Use

  • Non-MAUI .NET projects (use standard .NET SDK troubleshooting instead)
  • Xamarin.Forms apps (different toolchain and workload requirements)
  • Runtime app crashes unrelated to environment setup
  • App store publishing or signing issues
  • IDE-specific issues (Visual Studio or VS Code configuration)

Important: .NET Version Currency

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.

Inputs

  • A development machine running macOS, Windows, or Linux
  • Shell access (Bash on macOS/Linux, PowerShell on Windows)
  • Internet access for NuGet API queries and SDK downloads
  • Admin/sudo access may be required for installing SDKs and workloads
  • Bash prerequisites: curl, jq, and unzip (macOS/Linux)
  • PowerShell prerequisites: Invoke-RestMethod and System.IO.Compression (built-in on Windows)

Behavior

  • Run through ALL tasks autonomously
  • Re-validate after each fix
  • Iterate until complete or no further actions possible
  • After detecting platform (Task 1), load only the matching platform-specific references

Workflow

Task 1: Detect Environment

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

  • macOS: references/platform-requirements-macos.md, references/installation-commands-macos.md, references/troubleshooting-macos.md
  • Windows: references/platform-requirements-windows.md, references/installation-commands-windows.md, references/troubleshooting-windows.md
  • Linux: references/platform-requirements-linux.md

Task 2: Check .NET SDK

dotnet --info

Compare installed vs latest-sdk from https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json where support-phase is "active".

Task 3: Check MAUI Workloads

| Workload | macOS | Windows | Linux | |----------|-------|---------|-------| | maui | Required | Required | ❌ Use maui-android | | maui-android | Alias | Alias | Required | | android | Required | Required | Required | | ios | Required | Optional | N/A |

Task 4: Discover Requirements from NuGet

See references/workload-dependencies-discovery.md for complete process.

Query NuGet for workload manifest → extract WorkloadDependencies.json → get:

  • jdk.version range and jdk.recommendedVersion
  • androidsdk.packages, buildToolsVersion, apiLevel
  • xcode.version range

Task 5: Validate Java JDK

Only 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 the jdk.version range. 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 |

Task 6: Validate Android SDK

Check packages from androidsdk.packages, buildToolsVersion, apiLevel (Task 4). See references/installation-commands.md for sdkmanager commands.

Task 7: Validate Xcode (macOS Only)

xcodebuild -version

Compare against xcode.version range from Task 4. See references/installation-commands-macos.md.

Task 8: Validate Windows SDK (Windows Only)

The Windows SDK is typically installed as part of the .NET MAUI workload or Visual Studio. See references/installation-commands-windows.md.

Task 9: Remediation

See references/installation-commands.md for all commands.

Key rules:

  • Workloads: Always use --version flag. Never use workload update or workload repair.
  • JDK: Only install Microsoft OpenJDK. Do not set JAVA_HOME (auto-detected).
  • Android SDK: Use sdkmanager (from Android SDK command-line tools). On Windows use sdkmanager.bat.

Task 10: Re-validate

After each fix, re-run the relevant validation task. Iterate until all checks pass.

Validation

A successful run produces:

  • .NET SDK installed and matches an active release
  • All required workloads installed with consistent versions
  • Microsoft OpenJDK detected (java -version contains "Microsoft")
  • All required Android SDK packages installed (per WorkloadDependencies.json)
  • Xcode version in supported range (macOS only)
  • Windows SDK detected (Windows only)

Build Verification (Recommended)

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.

Run Verification (Optional — Ask User First)

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.

Common Pitfalls

  • 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.
  • Non-Microsoft JDK: Only Microsoft OpenJDK is supported. Other distributions (Oracle, Adoptium, Azul) will cause build failures even if the version is correct.
  • Unnecessary JAVA_HOME: Do not set JAVA_HOME. MAUI auto-detects JDK from known install paths. If JAVA_HOME is set to a non-Microsoft JDK (e.g., Temurin), report this as an anomaly — it may override auto-detection and cause failures. Let the user decide whether to unset it.
  • Hardcoded versions: Never hardcode SDK, workload, or dependency versions. Always discover them dynamically from the NuGet APIs (see Task 4).
  • Android SDK sdkmanager on Windows: Use sdkmanager.bat, not sdkmanager, on Windows.
  • Stale training data: LLM training data may reference outdated .NET versions. Always check the releases-index.json to discover the current active release.

References

  • references/workload-dependencies-discovery.md — NuGet API discovery process
  • references/microsoft-openjdk.md — JDK detection paths, identification, JAVA_HOME
  • references/installation-commands.md — .NET workloads, Android SDK (sdkmanager)
  • references/troubleshooting.md — Common errors and solutions
  • references/platform-requirements-{platform}.md — Platform-specific requirements
  • references/installation-commands-{platform}.md — Platform-specific install commands
  • references/troubleshooting-{platform}.md — Platform-specific troubleshooting

Official docs:

Related Skills

View on GitHub
GitHub Stars5.5k
CategoryMarketing
Updated1mo ago
Forks418

Languages

C#

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions