{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/dotnet-maui-doctor",
  "version": "1.0.1",
  "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.",
  "system_prompt_fragment": "# .NET MAUI Doctor\n\nValidate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.\n\n## When to Use\n\n- Setting up a new .NET MAUI development environment\n- Build errors mentioning missing SDKs, workloads, JDK, or Android components\n- Errors like \"Android SDK not found\", \"Java version\", or \"Xcode not found\"\n- Verifying environment health after SDK or OS updates\n\n## When Not to Use\n\n- Non-MAUI .NET projects (use standard .NET SDK troubleshooting instead)\n- Xamarin.Forms apps (different toolchain and workload requirements)\n- Runtime app crashes unrelated to environment setup\n- App store publishing or signing issues\n- IDE-specific issues (Visual Studio or VS Code configuration)\n\n## Important: .NET Version Currency\n\nYour 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.\n\n## Inputs\n\n- A development machine running macOS, Windows, or Linux\n- Shell access (Bash on macOS/Linux, PowerShell on Windows)\n- Internet access for NuGet API queries and SDK downloads\n- Admin/sudo access may be required for installing SDKs and workloads\n- **Bash prerequisites**: `curl`, `jq`, and `unzip` (macOS/Linux)\n- **PowerShell prerequisites**: `Invoke-RestMethod` and `System.IO.Compression` (built-in on Windows)\n\n## Behavior\n\n- Run through ALL tasks autonomously\n- Re-validate after each fix\n- Iterate until complete or no further actions possible\n- After detecting platform (Task 1), load only the matching platform-specific references\n\n## Workflow\n\n### Task 1: Detect Environment\n\n```bash\n# macOS\nsw_vers && uname -m\n\n# Windows\nsysteminfo | findstr /B /C:\"OS Name\" /C:\"OS Version\"\n\n# Linux\ncat /etc/os-release && uname -m\n```\n\nAfter detection, load the matching platform references:\n- **macOS**: `references/platform-requirements-macos.md`, `references/installation-commands-macos.md`, `references/troubleshooting-macos.md`\n- **Windows**: `references/platform-requirements-windows.md`, `references/installation-commands-windows.md`, `references/troubleshooting-windows.md`\n- **Linux**: `references/platform-requirements-linux.md`\n\n### Task 2: Check .NET SDK\n\n```bash\ndotnet --info\n```\n\nCompare installed vs `latest-sdk` from https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json where `support-phase` is `\"active\"`.\n\n### Task 3: Check MAUI Workloads\n\n| Workload | macOS | Windows | Linux |\n|----------|-------|---------|-------|\n| `maui` | Required | Required | ❌ Use `maui-android` |\n| `maui-android` | Alias | Alias | Required |\n| `android` | Required | Required | Required |\n| `ios` | Required | Optional | N/A |\n\n### Task 4: Discover Requirements from NuGet\n\nSee `references/workload-dependencies-discovery.md` for complete process.\n\nQuery NuGet for workload manifest → extract `WorkloadDependencies.json` → get:\n- `jdk.version` range and `jdk.recommendedVersion`\n- `androidsdk.packages`, `buildToolsVersion`, `apiLevel`\n- `xcode.version` range\n\n### Task 5: Validate Java JDK\n\n**Only Microsoft OpenJDK supported.** Verify `java -version` output contains \"Microsoft\". See `references/microsoft-openjdk.md` for detection paths.\n\n> Use the JDK version recommended by WorkloadDependencies.json (`jdk.recommendedVersion`), ensuring it satisfies the `jdk.version` range. Do not hardcode JDK versions.\n\n**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.\n\n| JAVA_HOME state | OK? | Action |\n|-----------------|-----|--------|\n| Not set | ✅ | None needed — auto-detection works |\n| Set to Microsoft JDK | ✅ | None needed |\n| Set to non-Microsoft JDK | ⚠️ | **Report as anomaly** — let user decide to unset or redirect |\n\n### Task 6: Validate Android SDK\n\nCheck packages from `androidsdk.packages`, `buildToolsVersion`, `apiLevel` (Task 4). See `references/installation-commands.md` for sdkmanager commands.\n\n### Task 7: Validate Xcode (macOS Only)\n\n```bash\nxcodebuild -version\n```\n\nCompare against `xcode.version` range from Task 4. See `references/installation-commands-macos.md`.\n\n### Task 8: Validate Windows SDK (Windows Only)\n\nThe Windows SDK is typically installed as part of the .NET MAUI workload or Visual Studio. See `references/installation-commands-windows.md`.\n\n### Task 9: Remediation\n\nSee `references/installation-commands.md` for all commands.\n\nKey rules:\n- **Workloads**: Always use `--version` flag. Never use `workload update` or `workload repair`.\n- **JDK**: Only install Microsoft OpenJDK. Do not set JAVA_HOME (auto-detected).\n- **Android SDK**: Use `sdkmanager` (from Android SDK command-line tools). On Windows use `sdkmanager.bat`.\n\n### Task 10: Re-validate\n\nAfter each fix, re-run the relevant validation task. Iterate until all checks pass.\n\n## Validation\n\nA successful run produces:\n- .NET SDK installed and matches an active release\n- All required workloads installed with consistent versions\n- Microsoft OpenJDK detected (`java -version` contains \"Microsoft\")\n- All required Android SDK packages installed (per WorkloadDependencies.json)\n- Xcode version in supported range (macOS only)\n- Windows SDK detected (Windows only)\n\n### Build Verification (Recommended)\n\nAfter all checks pass, create and build a test project to confirm the environment actually works:\n\n```bash\nTEMP_DIR=$(mktemp -d)\ndotnet new maui -o \"$TEMP_DIR/MauiTest\"\ndotnet build \"$TEMP_DIR/MauiTest\"\nrm -rf \"$TEMP_DIR\"\n```\n\nOn Windows, use `$env:TEMP` or `New-TemporaryFile` for the temp directory.\n\nIf the build succeeds, the environment is verified. If it fails, use the error output to diagnose remaining issues.\n\n### Run Verification (Optional — Ask User First)\n\nAfter a successful build, **ask the user** if they want to launch the app on a target platform to verify end-to-end:\n\n```bash\n# Replace net10.0 with the current major .NET version\ndotnet build -t:Run -f net10.0-android\ndotnet build -t:Run -f net10.0-ios        # macOS only\ndotnet build -t:Run -f net10.0-maccatalyst # macOS only\ndotnet build -t:Run -f net10.0-windows    # Windows only\n```\n\nOnly 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.\n\n## Common Pitfalls\n\n- **`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.\n- **`workload update` / `workload repair`**: Never use these commands. Always install workloads with an explicit `--version` flag to ensure version consistency.\n- **Non-Microsoft JDK**: Only Microsoft OpenJDK is supported. Other distributions (Oracle, Adoptium, Azul) will cause build failures even if the version is correct.\n- **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.\n- **Hardcoded versions**: Never hardcode SDK, workload, or dependency versions. Always discover them dynamically from the NuGet APIs (see Task 4).\n- **Android SDK `sdkmanager` on Windows**: Use `sdkmanager.bat`, not `sdkmanager`, on Windows.\n- **Stale training data**: LLM training data may reference outdated .NET versions. Always check the releases-index.json to discover the current active release.\n\n## References\n\n- `references/workload-dependencies-discovery.md` — NuGet API discovery process\n- `references/microsoft-openjdk.md` — JDK detection paths, identification, JAVA_HOME\n- `references/installation-commands.md` — .NET workloads, Android SDK (sdkmanager)\n- `references/troubleshooting.md` — Common errors and solutions\n- `references/platform-requirements-{platform}.md` — Platform-specific requirements\n- `references/installation-commands-{platform}.md` — Platform-specific install commands\n- `references/troubleshooting-{platform}.md` — Platform-specific troubleshooting\n\nOfficial docs:\n- [.NET MAUI Installation](https://learn.microsoft.com/en-us/dotnet/maui/get-started/installation)\n- [.NET SDK Downloads](https://dotnet.microsoft.com/download)\n- [Microsoft OpenJDK](https://learn.microsoft.com/en-us/java/openjdk/install)\n- [Android SDK Command-Line Tools](https://developer.android.com/studio#command-line-tools-only)\n- [Xcode Downloads](https://developer.apple.com/xcode/)",
  "applicable_domains": [
    "code",
    "dotnet",
    "engineering"
  ],
  "invocation": [
    "/dotnet-maui-doctor"
  ],
  "tags": [
    "dotnet-maui",
    "dotnet",
    "csharp",
    "microsoft"
  ],
  "authored_by": "anthropics",
  "source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md",
  "lifecycle": "stable",
  "category": "dotnet",
  "provenance": {
    "source": "dotnet/skills",
    "source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md",
    "author": "Microsoft / .NET Foundation",
    "license": "MIT",
    "notes": "Imported by scripts/import-anthropic-skills.py."
  }
}