Add dotnet-maui plugin with dotnet-maui-doctor skill

.github/CODEOWNERS

@@ -54,3 +54,7 @@
 # dotnet-data (data access, Entity Framework)
 /plugins/dotnet-data/skills/optimizing-ef-core-queries/ @dotnet/efteam
 /tests/dotnet-data/optimizing-ef-core-queries/ @dotnet/efteam
+
+# dotnet-maui
+/plugins/dotnet-maui/ @Redth @jfversluis
+/tests/dotnet-maui/ @Redth @jfversluis

.github/plugin/marketplace.json

@@ -28,6 +28,11 @@
       "name": "dotnet-upgrade",
       "source": "./plugins/dotnet-upgrade",
       "description": "Skills for migrating and upgrading .NET projects across framework versions, language features, and compatibility targets."
+    },
+    {
+      "name": "dotnet-maui",
+      "source": "./plugins/dotnet-maui",
+      "description": "Skills for .NET MAUI development: environment setup, diagnostics, and troubleshooting."
     }
   ]
 }

README.md

@@ -13,6 +13,7 @@ This repository contains the .NET team's curated set of core skills and custom a
 | [dotnet-diag](plugins/dotnet-diag/) | Skills for .NET performance investigations, debugging, and incident analysis. |
 | [dotnet-msbuild](plugins/dotnet-msbuild/) | Comprehensive MSBuild and .NET build skills: failure diagnosis, performance optimization, code quality, and modernization. |
 | [dotnet-upgrade](plugins/dotnet-upgrade/) | Skills for migrating and upgrading .NET projects across framework versions, language features, and compatibility targets. |
+| [dotnet-maui](plugins/dotnet-maui/) | Skills for .NET MAUI development: environment setup, diagnostics, and troubleshooting. |
 
 ## Installation
 

plugins/dotnet-maui/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "dotnet-maui",
+  "version": "0.1.0",
+  "description": "Skills for .NET MAUI development: environment setup, diagnostics, and troubleshooting.",
+  "skills": "./skills/"
+}

plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md

@@ -0,0 +1,206 @@
+---
+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.
+---
+
+# .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
+
+| 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)
+
+```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`.
+
+### 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:
+
+```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:
+- [.NET MAUI Installation](https://learn.microsoft.com/en-us/dotnet/maui/get-started/installation)
+- [.NET SDK Downloads](https://dotnet.microsoft.com/download)
+- [Microsoft OpenJDK](https://learn.microsoft.com/en-us/java/openjdk/install)
+- [Android SDK Command-Line Tools](https://developer.android.com/studio#command-line-tools-only)
+- [Xcode Downloads](https://developer.apple.com/xcode/)

plugins/dotnet-maui/skills/dotnet-maui-doctor/references/installation-commands-macos.md

@@ -0,0 +1,63 @@
+# macOS Installation Commands
+
+## Xcode
+
+### Install Xcode
+
+**Do not install Xcode from the App Store** — it can auto-update to a version newer than what .NET MAUI supports.
+
+Download a specific version from [Apple Developer Downloads](https://developer.apple.com/download/all/), matching the `xcode.version` range from WorkloadDependencies.json.
+
+> **Note**: Downloading from Apple Developer Downloads requires signing in with an Apple ID (with two-factor authentication). Xcode is approximately 12 GB and may take 30 minutes or more to download. The agent cannot automate this — tell the user to download Xcode manually, set expectations for the download size and wait time, then continue with the remaining steps.
+
+### Install Command Line Tools
+
+```bash
+xcode-select --install
+```
+
+### List Xcode Installations
+
+```bash
+ls -d /Applications/Xcode*.app 2>/dev/null
+xcodebuild -version
+xcode-select -p
+```
+
+### Set Active Xcode Version
+
+```bash
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+```
+
+### Accept Xcode License
+
+```bash
+sudo xcodebuild -license accept
+```
+
+### Verify Xcode Installation
+
+```bash
+xcodebuild -version
+xcrun simctl list devices available
+```
+
+---
+
+## iOS Simulators
+
+Only create a simulator if none exist. Prefer a recent iPhone device type with the latest available runtime.
+
+```bash
+# Check if any simulators already exist
+xcrun simctl list devices available
+
+# If none exist, find the latest iPhone device type and runtime
+xcrun simctl list devicetypes | grep iPhone
+xcrun simctl list runtimes | grep iOS
+
+# Create one using a chosen device type and runtime from the lists above
+# Replace <DEVICE_TYPE_ID> and <RUNTIME_ID> with identifiers from the commands above
+xcrun simctl create "My iPhone Simulator" "<DEVICE_TYPE_ID>" "<RUNTIME_ID>"
+```

plugins/dotnet-maui/skills/dotnet-maui-doctor/references/installation-commands-windows.md

@@ -0,0 +1,7 @@
+# Windows Installation Commands
+
+## Windows SDK
+
+The Windows SDK is required for WinUI 3 / Windows targets. It is typically installed automatically as part of the .NET MAUI workload or via the Visual Studio Installer.
+
+For standalone installation, see: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/