Official agent skill

.NET MAUI Doctor

by dotnet in dotnet/skills

Diagnoses and fixes .NET MAUI development environments by checking the .NET SDK, workloads, JDK, Android SDK, Xcode and Windows SDK against requirements read from NuGet.

OfficialMITAuto-check passedMobile

Install .NET MAUI Doctor

skills CLI
$ npx skills add dotnet/skills --skill dotnet-maui-doctor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install dotnet/skills dotnet-maui-doctor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/dotnet/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/dotnet-maui/skills/dotnet-maui-doctor .claude/skills/dotnet-maui-doctor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
dotnet-maui-doctor
GitHub stars
5.6k
Used in
1 other repo
Token cost
~2.4k tokens
SKILL.md length
914 words
Files
12 (incl. references)
Skills in repo
70
Repo updated
First seen
Licence
MIT

At a glance

Diagnoses and fixes .NET MAUI development environments by checking the .NET SDK, workloads, JDK, Android SDK, Xcode and Windows SDK against requirements read from NuGet.

  • Setting up a new .NET MAUI development machine
  • SKILL.md covers When to Use, When Not to Use, Important: .NET Version Currency and Inputs, plus 5 more sections
  • Calls dotnet, java and xcodebuild
  • Build errors that mention missing SDKs, workloads, the JDK or Android components

What it does

The skill works through a series of tasks on its own. It detects the platform (macOS, Windows or Linux), checks the .NET SDK with dotnet --info, then validates workloads, the Java JDK, the Android SDK, Xcode and the Windows SDK. It fixes what is missing and re-validates after each fix until nothing more can be done. Version requirements are never hardcoded: they are discovered at run time from NuGet and WorkloadDependencies.json, and the latest active .NET major release comes from releases-index.json rather than from the agent's memory.

After detection, only the matching platform references are loaded, covering platform requirements, installation commands and troubleshooting, plus notes on Microsoft OpenJDK and on discovering workload dependencies. It needs shell access (Bash with curl, jq and unzip on macOS and Linux, PowerShell on Windows), internet access for NuGet queries and downloads, and sometimes admin or sudo rights. It is not meant for non-MAUI .NET projects, Xamarin.Forms apps, runtime crashes unrelated to setup, app store publishing or IDE-specific configuration.

When your agent uses it

  • Setting up a new .NET MAUI development machine
  • Build errors that mention missing SDKs, workloads, the JDK or Android components
  • Errors such as Android SDK not found, a Java version problem or Xcode not found
  • Verifying that the environment still works after SDK or OS updates

Example prompts

  • “My MAUI build fails with Android SDK not found. Diagnose my environment and fix it.”
  • “Set up this Windows laptop for .NET MAUI development from scratch.”
  • “I updated macOS and now MAUI complains that Xcode is missing. Check my toolchain.”

Requirements

  • macOS, Windows or Linux with shell access
  • Internet access for NuGet queries and SDK downloads
  • curl, jq and unzip on macOS and Linux

What it can do on your machine

Read from SKILL.md and the folder at commit 1d40f95. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • dotnet
    • java
    • xcodebuild

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • learn.microsoft.com
    • dotnetcli.blob.core.windows.net
    • dotnet.microsoft.com
    • developer.android.com
    • developer.apple.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

.NET MAUI Doctor loads about 2.4k tokens when it runs, and up to ~11k if it reads all its reference files. Until then it costs about 167 tokens; SKILL.md has 914 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~167
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~11k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from dotnet/skills at commit 1d40f95, republished under its MIT licence (© dotnet). 914 words, ~2,382 tokens.

Download SKILL.mdSave it as .claude/skills/dotnet-maui-doctor/SKILL.md (or your agent's skills folder). This skill also uses 11 other files; get the full folder from GitHub.
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
bash
# 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
bash
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
mauiRequiredRequired❌ Use maui-android
maui-androidAliasAliasRequired
androidRequiredRequiredRequired
iosRequiredOptionalN/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)
bash
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.
Show full SKILL.md (373 more words)Show less
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)

After all checks pass, create and build a test project to confirm the environment actually works:

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

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

© dotnet, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 11 other files (references) in plugins/dotnet-maui/skills/dotnet-maui-doctor of dotnet/skills.

  • SKILL.md
  • references/installation-commands-macos.md
  • references/installation-commands-windows.md
  • references/installation-commands.md
  • references/microsoft-openjdk.md
  • references/platform-requirements-linux.md
  • references/platform-requirements-macos.md
  • references/platform-requirements-windows.md
  • references/troubleshooting-macos.md
  • references/troubleshooting-windows.md
  • references/troubleshooting.md
  • references/workload-dependencies-discovery.md

Open the folder on GitHubat commit 1d40f95

Used in 1 other repository

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in dotnet/skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

.NET MAUI Doctor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

.NET MAUI Doctor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
.NET MAUI Doctor this skilldotnet/skills5.6k1 repos~2.4kAutomated safety check: PassMIT
AppsFlyer Unity Plugin API ChangeAppsFlyerSDK/appsflyer-unity-plugin178—~514Automated safety check: PassMIT
Eas Simulatorexpo/skills2.7k—~6.6kAutomated safety check: NotesMIT
Find Untested Sourcesmicrosoft/testfx1k2 repos~3.3kAutomated safety check: PassMIT
Frb Android Emulator Preparefzyzcjy/flutter_rust_bridge5.4k—~2.1kAutomated safety check: NotesMIT
Expo Brownfield Integrationmweinbach/agent-coworker1562 repos~900Automated safety check: NotesCustom licence

Similar skills

  • AppsFlyer Unity Plugin API Change

    AppsFlyerSDK/appsflyer-unity-plugin

    Guides API changes in the AppsFlyer Unity plugin across the C# layer and the Android Java and iOS Objective-C bridges, ending with a compatibility-risk report.

    178 GitHub stars~514 tokensUpdated 6 days ago
    MobileAuto-check passed
  • Eas Simulator

    expo/skills

    Official

    Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud.

    2.7k GitHub stars~6.6k tokensUpdated 3 days ago
    MobileAuto-check: notes
  • Find Untested Sources

    microsoft/testfx

    Official

    MANDATORY for static source-to-test pairing: find or list source files/modules without corresponding tests, or suggest test locations from repository structure.

    1k GitHub starsUsed in 2 repos~3.3k tokens
    MobileAuto-check passed
  • Frb Android Emulator Prepare

    fzyzcjy/flutter_rust_bridge

    A skill your agent uses when preparing, installing, diagnosing, or explaining the host Android Emulator environment for flutterrustbridge local runtime validation, including Android SDK command-line…

    5.4k GitHub stars~2.1k tokensUpdated yesterday
    MobileAuto-check: notes
  • Expo Brownfield Integration

    mweinbach/agent-coworker

    Helps add Expo and React Native to an existing native iOS or Android app, and choose between a prebuilt AAR or XCFramework and a fully integrated build.

    156 GitHub starsUsed in 2 repos~900 tokens
    MobileAuto-check: notes
  • Simulator Audio E2E

    hyochan/react-native-nitro-sound

    Build and run repeatable react-native-nitro-sound recorder/player regression tests on an iOS Simulator or Android emulator, with explicit virtual-device selection, microphone permission, Maestro…

    961 GitHub stars~1.1k tokensUpdated 11 days ago
    MobileAuto-check passed

More from dotnet/skills

All 70 skills in this repo
  • Official

    Resolves .NET runtime frames in Apple .ips crash logs to function names, source files and line numbers using dSYM symbols, atos and the Microsoft symbol server.

    5.6k GitHub starsUsed in 1 repo~2.4k tokens
    Auto-check passed
  • Official

    Scans C# and .NET code for about 50 performance anti-patterns and reports prioritized findings with concrete fixes, at a scan depth you choose.

    5.6k GitHub starsUsed in 3 repos~3.1k tokens
    Auto-check passed
  • Official

    Resolves native crash frames from .NET Android tombstones to function names, source files and line numbers using BuildIds, Microsoft's symbol server and llvm-symbolizer.

    5.6k GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed
  • Microbenchmarking

    dotnet/skills

    Official

    Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating, running, configuring, or reviewing BDN benchmarks.

    5.6k GitHub starsUsed in 3 repos~3.3k tokens
    Auto-check passed
  • Official

    Makes .NET projects compatible with Native AOT and trimming by resolving IL trim and AOT analyzer warnings through annotations rather than suppressions.

    5.6k GitHub starsUsed in 2 repos~4.2k tokens
    Auto-check passed
  • Official

    Configures automatic crash dumps or captures dumps from running processes for modern .NET apps on Linux, macOS and Windows, including Docker and Kubernetes.

    5.6k GitHub starsUsed in 2 repos~1.1k tokens
    Auto-check passed

Categories

Questions about .NET MAUI Doctor

What does .NET MAUI Doctor do?

Diagnoses and fixes .NET MAUI development environments by checking the .NET SDK, workloads, JDK, Android SDK, Xcode and Windows SDK against requirements read from NuGet. The skill works through a series of tasks on its own.NET SDK with dotnet --info, then validates workloads, the Java JDK, the Android SDK, Xcode and the Windows SDK.

When should I use .NET MAUI Doctor?

.NET MAUI Doctor fits situations like: setting up a new .NET MAUI development machine; build errors that mention missing SDKs, workloads, the JDK or Android components; errors such as Android SDK not found, a Java version problem or Xcode not found; verifying that the environment still works after SDK or OS updates.

How do I install .NET MAUI Doctor in Claude Code?

Run `npx skills add dotnet/skills --skill dotnet-maui-doctor -a claude-code`. Or copy the skill folder (plugins/dotnet-maui/skills/dotnet-maui-doctor in dotnet/skills) into .claude/skills/dotnet-maui-doctor in your project. Claude Code loads it when a task matches its description.

How do I install .NET MAUI Doctor in Codex?

Run `npx skills add dotnet/skills --skill dotnet-maui-doctor -a codex`. Or copy the skill folder (plugins/dotnet-maui/skills/dotnet-maui-doctor in dotnet/skills) into .agents/skills/dotnet-maui-doctor in your project. Codex loads it when a task matches its description.

Can I use .NET MAUI Doctor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add dotnet/skills --skill dotnet-maui-doctor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/dotnet-maui-doctor, .gemini/skills/dotnet-maui-doctor, .github/skills/dotnet-maui-doctor and .opencode/skills/dotnet-maui-doctor in your project.

What does .NET MAUI Doctor need to run?

Going by SKILL.md and its folder, .NET MAUI Doctor needs the command-line tools its instructions call (dotnet, java and xcodebuild). Our summary lists: macOS, Windows or Linux with shell access; Internet access for NuGet queries and SDK downloads; curl, jq and unzip on macOS and Linux.

Does .NET MAUI Doctor access the network?

SKILL.md names 5 domains. As links in the text: learn.microsoft.com, dotnetcli.blob.core.windows.net, dotnet.microsoft.com, developer.android.com and developer.apple.com. This is read from the text; nothing was executed.

Is .NET MAUI Doctor safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does .NET MAUI Doctor use?

.NET MAUI Doctor is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does .NET MAUI Doctor use?

About 2.4k tokens (SKILL.md is roughly 9.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 8.7k tokens, read only when the agent opens those files.

What are the alternatives to .NET MAUI Doctor?

Skills that share tags, products or a category with .NET MAUI Doctor: AppsFlyer Unity Plugin API Change (AppsFlyerSDK/appsflyer-unity-plugin, 178 stars), Eas Simulator (expo/skills, 2.7k stars), Find Untested Sources (microsoft/testfx, 1k stars) and Frb Android Emulator Prepare (fzyzcjy/flutter_rust_bridge, 5.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains .NET MAUI Doctor?

dotnet (a GitHub organization, an official publisher) maintains it in dotnet/skills, which has 5,594 GitHub stars. The repository holds 70 skills in this directory. The repository was last updated on October 9, 2026.

Source: dotnet/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.