OpenSkillIndex← back to search
claude-code

Skills dotnet-maui-doctor

install
source · Clone the upstream repo
git clone https://github.com/dotnet/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/dotnet/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/dotnet-maui/skills/dotnet-maui-doctor" ~/.claude/skills/dotnet-skills-dotnet-maui-doctor && rm -rf "$T"
manifest: plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md
source content

.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

WorkloadmacOSWindowsLinux
maui
RequiredRequired❌ Use 
maui-android
maui-android
AliasAliasRequired
android
RequiredRequiredRequired
ios
RequiredOptionalN/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 stateOK?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: