@appium/mcp-documentation 1.0.3 → 1.0.5

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/xcuitest-element-lookup.md

@@ -0,0 +1,23 @@
+# XCUITest Element Lookup Troubleshooting
+
+## Official Reference
+- `https://appium.github.io/appium-xcuitest-driver/latest/guides/elements-lookup-troubleshooting/`
+
+## When To Read This
+- elements visible to a human are missing in Appium Inspector
+- source dumps look incomplete
+- an iOS locator works intermittently
+- lookup is unexpectedly slow
+
+Use the official guide for the full symptom matrix. This page keeps only the local checks that are easiest to miss.
+
+## Local Triage
+1. Collect source from the same environment as the failing test: same simulator or device, OS version, app build, orientation, and permission state.
+2. Confirm the element exists in the current source dump before changing selector syntax.
+3. Inspect the attributes the element actually exposes: `name`, `label`, `value`, type, visibility, and enabled state.
+4. Verify the active application and window in WebDriverAgent. System alerts, share sheets, and other overlays may belong to a different active app.
+5. Change snapshot-related settings only after confirming a deep or incomplete tree problem, then compare the same single lookup before and after.
+
+## Notes
+- A missing element in source is usually an accessibility, app-state, or active-application problem first, not a locator problem.
+- If the app uses web content, confirm the current context before continuing native lookup debugging.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/xcuitest-locators.md

@@ -0,0 +1,16 @@
+# XCUITest Locators
+
+## Official Reference
+- `https://appium.github.io/appium-xcuitest-driver/latest/reference/locator-strategies/`
+
+Use the driver docs for the full strategy ordering and syntax. This page keeps only the local debugging notes that help choose among them.
+
+## Local Guidance
+- On XCUITest, `id`, `name`, and `accessibility id` are treated as synonyms over the element `name` attribute. Check the current source before assuming that attribute is stable in this app.
+- Use `-ios predicate string` or `-ios class chain` when you need native filtering or hierarchy scoping; keep the query tied to attributes that are visible in source.
+- Treat `xpath` as a fallback for cases where the source does not expose a simpler native path. If `xpath` is the first thing that works, use it to learn the tree and then replace it if a native selector is available.
+- If the element is absent from source, stop iterating locator syntax and switch to the element-lookup troubleshooting flow.
+
+## Validation
+- Re-run the exact failing lookup against the same screen.
+- Prefer the simplest native selector that still uniquely identifies the element.

package/src/resources/submodules/appium-skills/skills/appium-troubleshooting/references/xcuitest-troubleshooting.md

@@ -0,0 +1,52 @@
+# XCUITest Troubleshooting
+
+## Official References
+- `https://appium.github.io/appium-xcuitest-driver/latest/guides/troubleshooting/`
+- `https://github.com/appium/appium-xcuitest-driver`
+
+## When To Read This
+- WebDriverAgent does not build, install, or stay reachable
+- session startup stalls or fails on simulator or real device
+- app install or launch fails on iOS
+- system alerts block automation
+- simulator or real-device state looks corrupted
+
+This page is a compact entry point into the official XCUITest troubleshooting guide.
+
+## Local Triage Map
+| Symptom | Verify First | Avoid Until Confirmed |
+|---|---|---|
+| WDA build or signing failure | `xcode-select`, `xcodebuild -version`, `appium driver doctor xcuitest`, and real-device signing setup | changing unrelated test capabilities |
+| Proxy timeout or connection reset right after session start | fresh Appium logs, WDA reachability, and real-device unlock/trust/Developer Mode state | blaming locators or app logic |
+| App install or launch fails | app binary compatibility with the target runtime or device | treating it as a generic WDA failure |
+| System alert blocks the test | whether the alert should be explicitly handled or automatically accepted/dismissed | enabling auto-alert handling without matching test intent |
+| One simulator behaves differently from others | one clean shutdown and retry | erase/reset before confirming corruption |
+
+## Useful Checks
+```bash
+xcodebuild -version
+xcode-select -p
+appium driver doctor xcuitest
+xcrun simctl list devices
+xcrun simctl list runtimes
+grep -i "WebDriverAgent\|Proxying\|timed out" <appium-server-log-file>
+```
+
+## Real Device WDA Reachability
+- If WDA builds but commands time out right after session start on a real device, verify that the Appium log is actually proxying to a reachable WDA URL, typically `http://localhost:8100` when port forwarding is active.
+- If you manage WDA yourself, confirm the `appium:webDriverAgentUrl` value points to the actual reachable WDA endpoint, and supply `appium:wdaRemotePort` when the remote device port differs from the local forwarded port.
+- Prefer this real-device check before simulator-only recovery steps.
+
+## Real Device WDA Reachability Sequence
+1. Capture the Appium server log lines around the first timed out command and confirm which WDA URL Appium is proxying to.
+2. If the environment forwards the device port locally, run:
+   ```bash
+   curl -sf http://localhost:8100/status
+   ```
+   A healthy response means the forwarded WDA endpoint is reachable from the host.
+3. If you set `appium:webDriverAgentUrl`, compare it directly with the reachable endpoint. If the device-side port is not the default `8100`, set `appium:wdaRemotePort` to the device-side port that WDA actually listens on.
+4. Only after the reachability check passes should you move on to deeper app or locator troubleshooting.
+
+## Notes
+- Do not treat every iOS launch failure as a locator issue; many are WDA or device-state problems.
+- If the issue only happens on one real device or one simulator runtime, include that environment detail in the root-cause summary.

package/src/resources/submodules/appium-skills/skills/environment-setup-android/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: "environment-setup-android"
+description: "Prepare and validate Android SDK, Java, and device tooling for Appium Android drivers"
+metadata:
+  last_modified: "Mon, 27 Apr 2026 22:00:00 GMT"
+
+---
+# environment-setup-android
+
+## Goal
+Prepares a working Android automation environment for Appium by validating Java, Android SDK command-line tools, required SDK packages, environment variables, and ADB device visibility, with a verify-and-fix loop until all mandatory checks pass.
+
+## Decision Logic
+- If host OS is unsupported for Android SDK setup: stop and ask the user to switch to macOS, Linux, or Windows.
+- If `java -version` and `javac -version` already succeed: keep the existing Java setup and do not reconfigure `JAVA_HOME`.
+- If host OS is macOS and Java setup is needed (fresh environment): use Android Studio app setup as the primary method for both `ANDROID_HOME` (`$HOME/Library/Android/sdk`) and `JAVA_HOME` (Android Studio JBR). Check both `/Applications/Android Studio.app` and `$HOME/Applications/Android Studio.app`, and prefer the official direct download flow before Homebrew.
+- If host OS is Linux and Java setup is needed (fresh environment): use Android Studio bundled JBR as the primary method when Android Studio is installed, then fallback to distro/package-manager OpenJDK.
+- If host OS is Windows and Java setup is needed (fresh environment): use Android Studio bundled JBR as the primary method when Android Studio is installed, then fallback to Microsoft OpenJDK package install.
+- If host OS is Linux: use package manager + `$HOME/Android/Sdk` conventions.
+- If host OS is Windows: use Android SDK tools with persistent user environment variables.
+- If `java` or `javac` is missing: run step 3 to install/configure Java.
+- If the user wants official Android tooling setup flow: download Android Studio from the official site first, use its bundled JBR for Java, then bootstrap the SDK with the official `sdkmanager`.
+- If `ANDROID_HOME` is unset/empty or the `ANDROID_HOME` path does not exist: run step 2 to install command-line tools and create the SDK path.
+- If Java tooling is missing or broken (`java`/`javac` checks fail): run step 3 before Android SDK package/license commands.
+- If `adb` is missing: install `platform-tools` via `sdkmanager`.
+- If emulator binary is missing under `ANDROID_HOME/emulator/emulator` (or Windows equivalent): install emulator packages.
+- Prepare emulator instances using the latest stable system-image version by default.
+- Use host-optimized emulator architecture (native architecture first, then fallback architecture).
+- Skip step 7 emulator preparation if at least one device is already connected or at least one emulator instance already exists.
+- If required SDK packages are missing: install them and re-run checks.
+
+## Instructions
+1. **Detect OS and validate Java/base tooling**
+   macOS/Linux:
+   ```bash
+   uname -s
+   java -version
+   javac -version
+   echo "$JAVA_HOME"
+   command -v adb
+   ls "$ANDROID_HOME/emulator/emulator"
+   test -x "$ANDROID_HOME/emulator/emulator" && echo "emulator binary: OK"
+   ```
+   Windows PowerShell:
+   ```powershell
+   [System.Environment]::OSVersion.VersionString
+   java -version
+   javac -version
+   $env:JAVA_HOME
+   Get-Command adb.exe -ErrorAction SilentlyContinue
+   Test-Path "$env:ANDROID_HOME\emulator\emulator.exe"
+   ```
+
+2. **Install Android SDK tooling when `ANDROID_HOME` path is missing**
+   Trigger checks:
+   - macOS/Linux:
+   ```bash
+   [ -n "$ANDROID_HOME" ] && [ -d "$ANDROID_HOME" ] || echo "run step 2"
+   ```
+   - Windows PowerShell:
+   ```powershell
+   if (-not $env:ANDROID_HOME -or -not (Test-Path $env:ANDROID_HOME)) { "run step 2" }
+   ```
+   Option A (Android Studio app path; macOS priority when app exists):
+   - Download Android Studio from `https://developer.android.com/studio`.
+   - On macOS, check for the app in both `/Applications/Android Studio.app` and `$HOME/Applications/Android Studio.app`.
+   - You may either complete first launch and install SDK components from SDK Manager, or use the bundled JBR plus the official command-line tools zip to bootstrap the SDK non-interactively with `sdkmanager`.
+   - Use platform default SDK path after setup:
+     - macOS: `$HOME/Library/Android/sdk`
+     - Linux: `$HOME/Android/Sdk`
+     - Windows: `%LOCALAPPDATA%\Android\Sdk`
+
+   Option B (CLI tools only):
+   - macOS official command-line tools example:
+   ```bash
+   curl -L -o /tmp/commandlinetools-mac-latest.zip https://dl.google.com/android/repository/commandlinetools-mac-14742923_latest.zip
+   unzip -q /tmp/commandlinetools-mac-latest.zip -d /tmp/android-cmdline-tools
+   export JAVA_HOME="$HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home"
+   if [ ! -d "$JAVA_HOME" ]; then
+     export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
+   fi
+   export PATH="$JAVA_HOME/bin:$PATH"
+   /tmp/android-cmdline-tools/cmdline-tools/bin/sdkmanager --sdk_root="$HOME/Library/Android/sdk" "cmdline-tools;latest"
+   ```
+   - macOS/Homebrew fallback example:
+   ```bash
+   [ -d "/Applications/Android Studio.app" ] || brew install --cask android-commandlinetools
+   mkdir -p "$HOME/Library/Android/sdk/cmdline-tools/latest"
+   cp -R /opt/homebrew/share/android-commandlinetools/* "$HOME/Library/Android/sdk/cmdline-tools/latest/"
+   ```
+   - Linux example (Debian/Ubuntu-style prerequisites + cmdline tools placement):
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y unzip wget openjdk-21-jdk
+   mkdir -p "$HOME/Android/Sdk/cmdline-tools/latest"
+   ```
+   - Windows example (PowerShell, after extracting Android command-line tools zip):
+   ```powershell
+   New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Android\Sdk\cmdline-tools\latest"
+   ```
+
+3. **Configure Java for fresh environments (skip if Java already works)**
+   Trigger checks:
+   - macOS/Linux:
+   ```bash
+   if command -v java >/dev/null 2>&1 && command -v javac >/dev/null 2>&1; then
+     java -version >/dev/null 2>&1 && javac -version >/dev/null 2>&1 && echo "Java already available; skip step 3" || echo "run step 3"
+   else
+     echo "run step 3"
+   fi
+   ```
+   - Windows PowerShell:
+   ```powershell
+   if ((Get-Command java.exe -ErrorAction SilentlyContinue) -and (Get-Command javac.exe -ErrorAction SilentlyContinue)) {
+     java -version *> $null
+     if ($LASTEXITCODE -eq 0) {
+       javac -version *> $null
+       if ($LASTEXITCODE -eq 0) { "Java already available; skip step 3" } else { "run step 3" }
+     } else { "run step 3" }
+   } else { "run step 3" }
+   ```
+   macOS primary method for fresh setup (Android Studio bundled JBR):
+   ```bash
+   if [ -d "$HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home" ]; then
+     export JAVA_HOME="$HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home"
+     export PATH="$JAVA_HOME/bin:$PATH"
+     java -version
+     javac -version
+   elif [ -d "/Applications/Android Studio.app/Contents/jbr/Contents/Home" ]; then
+     export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
+     export PATH="$JAVA_HOME/bin:$PATH"
+     java -version
+     javac -version
+   else
+     echo "Android Studio JBR not found; use fallback method below"
+   fi
+   ```
+   macOS fallback method (only when Android Studio is not installed):
+   ```bash
+   brew install --cask temurin
+   export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+   export PATH="$JAVA_HOME/bin:$PATH"
+   java -version
+   javac -version
+   ```
+   Linux primary method for fresh setup (Android Studio bundled JBR):
+   ```bash
+   if [ -d "$HOME/android-studio/jbr" ]; then
+     export JAVA_HOME="$HOME/android-studio/jbr"
+   elif [ -d "/opt/android-studio/jbr" ]; then
+     export JAVA_HOME="/opt/android-studio/jbr"
+   elif [ -d "/usr/local/android-studio/jbr" ]; then
+     export JAVA_HOME="/usr/local/android-studio/jbr"
+   else
+     echo "Android Studio JBR not found; use fallback method below"
+   fi
+   if [ -n "$JAVA_HOME" ] && [ -d "$JAVA_HOME" ]; then
+     export PATH="$JAVA_HOME/bin:$PATH"
+     java -version
+     javac -version
+   fi
+   ```
+   Linux fallback method (OpenJDK 21 example):
+   ```bash
+   export JAVA_HOME="/usr/lib/jvm/java-21-openjdk-amd64"
+   export PATH="$JAVA_HOME/bin:$PATH"
+   java -version
+   javac -version
+   ```
+   Windows primary method for fresh setup (Android Studio bundled JBR, persist for current user):
+   ```powershell
+   $studioJbrCandidates = @(
+     "$env:LOCALAPPDATA\Programs\Android Studio\jbr",
+     "C:\Program Files\Android\Android Studio\jbr"
+   )
+   $studioJbr = $studioJbrCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
+   if ($studioJbr) {
+     [Environment]::SetEnvironmentVariable('JAVA_HOME', $studioJbr, 'User')
+     $currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+     if ($currentPath -notlike "*$studioJbr\bin*") {
+       [Environment]::SetEnvironmentVariable('Path', "$currentPath;$studioJbr\bin", 'User')
+     }
+     $env:JAVA_HOME = [Environment]::GetEnvironmentVariable('JAVA_HOME', 'User')
+     $env:PATH = "$studioJbr\bin;$env:PATH"
+     java -version
+     javac -version
+   } else {
+     "Android Studio JBR not found; use fallback method below"
+   }
+   ```
+   Windows fallback method (only when Android Studio is not installed):
+   ```powershell
+   winget install -e --id Microsoft.OpenJDK.17 --accept-source-agreements --accept-package-agreements
+   $jdkRoot = Get-ChildItem "C:\Program Files\Microsoft" -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -like 'jdk-*' } | Sort-Object Name -Descending | Select-Object -First 1
+   if ($jdkRoot) {
+     [Environment]::SetEnvironmentVariable('JAVA_HOME', $jdkRoot.FullName, 'User')
+     $currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+     if ($currentPath -notlike "*$($jdkRoot.FullName)\\bin*") {
+       [Environment]::SetEnvironmentVariable('Path', "$currentPath;$($jdkRoot.FullName)\\bin", 'User')
+     }
+     $env:JAVA_HOME = [Environment]::GetEnvironmentVariable('JAVA_HOME', 'User')
+     $env:PATH = "$env:JAVA_HOME\\bin;$env:PATH"
+   }
+   java -version
+   javac -version
+   ```
+
+4. **Configure Android environment variables and PATH**
+   macOS (priority: Android Studio SDK path):
+   ```bash
+   export ANDROID_HOME="$HOME/Library/Android/sdk"
+   export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/emulator:$PATH"
+   echo "$ANDROID_HOME"
+   command -v adb
+   ls "$ANDROID_HOME/emulator/emulator"
+   ```
+   Linux:
+   ```bash
+   export ANDROID_HOME="$HOME/Android/Sdk"
+   export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
+   echo "$ANDROID_HOME"
+   command -v adb
+   ls "$ANDROID_HOME/emulator/emulator"
+   ```
+   Windows PowerShell (persist for current user):
+   ```powershell
+   [Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", 'User')
+   $androidPaths = "$env:LOCALAPPDATA\Android\Sdk\platform-tools;$env:LOCALAPPDATA\Android\Sdk\cmdline-tools\latest\bin"
+   $currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+   if ($currentPath -notlike "*$androidPaths*") {
+     [Environment]::SetEnvironmentVariable('Path', "$currentPath;$androidPaths", 'User')
+   }
+   $env:ANDROID_HOME = [Environment]::GetEnvironmentVariable('ANDROID_HOME', 'User')
+   ```
+
+5. **Accept SDK licenses and install required packages**
+   macOS/Linux:
+   ```bash
+   if command -v sdkmanager >/dev/null 2>&1; then yes | sdkmanager --sdk_root="$ANDROID_HOME" --licenses; fi
+   if command -v sdkmanager >/dev/null 2>&1; then sdkmanager --sdk_root="$ANDROID_HOME" "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator"; fi
+   ```
+   Windows PowerShell:
+   ```powershell
+   if (Get-Command sdkmanager.bat -ErrorAction SilentlyContinue) { cmd /c "(for /l %i in (1,1,200) do @echo y)| sdkmanager.bat --licenses" }
+   if (Get-Command sdkmanager.bat -ErrorAction SilentlyContinue) { sdkmanager.bat "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator" }
+   ```
+    If license acceptance still fails in headless CI-like runs, pre-seed license hashes and retry package install:
+    ```powershell
+    $licensesDir = "$env:ANDROID_HOME\licenses"
+    New-Item -ItemType Directory -Force $licensesDir | Out-Null
+    Set-Content -Path "$licensesDir\android-sdk-license" -Value "24333f8a63b6825ea9c5514f83c2829b004d1fee`n8933bad161af4178b1185d1a37fbf41ea5269c55`nd56f5187479451eabf01fb78af6dfcb131a6481e"
+    ```
+
+6. **Verify Android SDK and ADB state**
+   macOS/Linux:
+   ```bash
+   if command -v sdkmanager >/dev/null 2>&1; then sdkmanager --list | head -n 80; fi
+   adb version
+   command -v emulator
+   ls "$ANDROID_HOME/emulator/emulator"
+   test -x "$ANDROID_HOME/emulator/emulator" && echo "emulator binary: OK"
+   ```
+   Windows PowerShell:
+   ```powershell
+   if (Get-Command sdkmanager.bat -ErrorAction SilentlyContinue) { sdkmanager.bat --list }
+   adb.exe version
+   Test-Path "$env:ANDROID_HOME\emulator\emulator.exe"
+   ```
+
+7. **Optional emulator instance preparation (if no physical device is connected and no emulator exists)**
+   Skip step 7 when either of the following is true:
+   - At least one device is already connected (`adb devices` shows a `device` entry)
+   - At least one emulator instance already exists (`emulator -list-avds` is non-empty)
+
+   Prepare an emulator instance using the latest stable system-image version and host-optimized architecture only when both are false.
+   macOS/Linux (prefer native architecture first, then fallback):
+   ```bash
+   ARCH=$(uname -m)
+   if [ "$ARCH" = "arm64" ] || [ "$ARCH" = "aarch64" ]; then
+     PRIMARY_ARCH="arm64-v8a"
+     FALLBACK_ARCH="x86_64"
+   else
+     PRIMARY_ARCH="x86_64"
+     FALLBACK_ARCH="arm64-v8a"
+   fi
+   LATEST_API=$(sdkmanager --list | grep -o "system-images;android-[0-9]\+;google_apis;${PRIMARY_ARCH}" | sed 's/.*android-\([0-9]\+\).*/\1/' | sort -n | tail -1)
+   IMAGE_ARCH="$PRIMARY_ARCH"
+   if [ -z "$LATEST_API" ]; then
+     LATEST_API=$(sdkmanager --list | grep -o "system-images;android-[0-9]\+;google_apis;${FALLBACK_ARCH}" | sed 's/.*android-\([0-9]\+\).*/\1/' | sort -n | tail -1)
+     IMAGE_ARCH="$FALLBACK_ARCH"
+   fi
+   IMAGE="system-images;android-${LATEST_API};google_apis;${IMAGE_ARCH}"
+   sdkmanager "$IMAGE"
+   echo "no" | avdmanager create avd -n "api${LATEST_API}-google-${IMAGE_ARCH}" -k "$IMAGE"
+   emulator -list-avds
+   ```
+   Windows PowerShell (prefer x86_64, fallback arm64-v8a):
+   ```powershell
+   $primaryArch = "x86_64"
+   $fallbackArch = "arm64-v8a"
+   $matches = sdkmanager.bat --list | Select-String "system-images;android-[0-9]+;google_apis;$primaryArch"
+   $imageArch = $primaryArch
+   if (-not $matches) {
+     $matches = sdkmanager.bat --list | Select-String "system-images;android-[0-9]+;google_apis;$fallbackArch"
+     $imageArch = $fallbackArch
+   }
+   $latestApi = ($matches | ForEach-Object { [int]([regex]::Match($_.Line, 'android-(\d+)').Groups[1].Value) } | Sort-Object)[-1]
+   $image = "system-images;android-$latestApi;google_apis;$imageArch"
+   sdkmanager.bat $image
+   cmd /c "echo no| avdmanager.bat create avd -n api$latestApi-google-$imageArch -k $image"
+   emulator.exe -list-avds
+   ```
+   Report version details in the task result:
+   - macOS/Linux:
+   ```bash
+   emulator -version
+   emulator -list-avds
+   if command -v sdkmanager >/dev/null 2>&1; then sdkmanager --list | grep "system-images;android-" | head -n 20; fi
+   ```
+   - Windows PowerShell:
+   ```powershell
+   emulator.exe -version
+   emulator.exe -list-avds
+   if (Get-Command sdkmanager.bat -ErrorAction SilentlyContinue) { sdkmanager.bat --list | Select-String "system-images;android-" | Select-Object -First 20 }
+   ```
+
+8. **Completion criteria**
+   Mark complete only when all are true:
+   - `java -version` and `javac -version` succeed
+   - `adb` is executable from `PATH`
+   - Emulator binary exists under `ANDROID_HOME/emulator/emulator` (or `%ANDROID_HOME%\emulator\emulator.exe` on Windows)
+   - Required SDK packages are installed (`platform-tools`, one platform, one build-tools version)
+    - Existing Java setup is preserved when Java already works (no forced reconfiguration)
+    - On fresh setup, Android Studio bundled JBR is used as `JAVA_HOME` when Android Studio is present (macOS/Linux/Windows)
+   - Android environment checks pass without requiring a connected device
+   - Latest stable emulator/system-image version is prepared with host-optimized architecture only when no connected devices and no existing emulators are present; otherwise step 7 is skipped and current version details are reported in the task result
+
+## Constraints
+- Always use detect-first behavior and install only missing components.
+- Re-run validation commands after each install/config change.
+- Do not report success if `adb` is unavailable or emulator binary check fails.
+- Treat optional dependencies and optional doctor warnings as non-blocking unless the user requests those features.
+- Ask the user before installing optional dependencies; do not install them by default.
+- If privileged commands are needed, pause and provide exact commands for user execution.
+- Keep Android setup independent from Appium driver installation steps.
+- Use shell-appropriate commands (`bash` for macOS/Linux, PowerShell/cmd for Windows).

package/src/resources/submodules/appium-skills/skills/environment-setup-bundletool/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "environment-setup-bundletool"
+description: "Install and validate bundletool.jar from GitHub releases for optional UiAutomator2/Espresso capabilities"
+metadata:
+  last_modified: "Thu, 12 Mar 2026 03:25:00 GMT"
+
+---
+# environment-setup-bundletool
+
+## Goal
+Installs and validates `bundletool.jar` from official GitHub releases so Android App Bundle tooling is available when explicitly requested for UiAutomator2 or Espresso setup.
+
+## Decision Logic
+- If host OS is unsupported: stop and ask the user to run on macOS, Linux, or Windows.
+- If user did not explicitly request bundletool setup: skip this skill.
+- If `bundletool.jar` is already resolvable via `PATH`: do not reinstall; validate and report current version.
+- If `bundletool.jar` is not present in `PATH`: download the latest release asset (`bundletool-all-*.jar`) from `https://github.com/google/bundletool/releases` and place it in a `PATH` directory.
+
+## Instructions
+1. **Detect OS and current bundletool availability**
+   macOS/Linux:
+   ```bash
+   uname -s
+   command -v bundletool.jar || echo "bundletool.jar not found"
+   if command -v bundletool.jar >/dev/null 2>&1; then java -jar "$(command -v bundletool.jar)" version; fi
+   ```
+   Windows PowerShell:
+   ```powershell
+   [System.Environment]::OSVersion.VersionString
+   $btPath = ($env:Path -split ';' | Where-Object { $_ -and (Test-Path (Join-Path $_ 'bundletool.jar')) } | ForEach-Object { Join-Path $_ 'bundletool.jar' } | Select-Object -First 1)
+   $btPath
+   if ($btPath) { java -jar $btPath version }
+   ```
+
+2. **Download latest `bundletool-all-*.jar` when missing**
+   macOS/Linux:
+   ```bash
+   mkdir -p "$HOME/bin"
+   RELEASE_API="https://api.github.com/repos/google/bundletool/releases/latest"
+   DOWNLOAD_URL=$(curl -fsSL "$RELEASE_API" | grep -Eo 'https://github.com/google/bundletool/releases/download/[^\"]+/bundletool-all-[^\"]+\.jar' | head -n 1)
+   test -n "$DOWNLOAD_URL"
+   curl -fL "$DOWNLOAD_URL" -o "$HOME/bin/bundletool.jar"
+   chmod +x "$HOME/bin/bundletool.jar"
+   export PATH="$HOME/bin:$PATH"
+   ```
+   Windows PowerShell:
+   ```powershell
+   $targetDir = "$HOME\bin"
+   New-Item -ItemType Directory -Force $targetDir | Out-Null
+   $release = Invoke-RestMethod "https://api.github.com/repos/google/bundletool/releases/latest"
+   $asset = $release.assets | Where-Object { $_.name -match '^bundletool-all-.*\.jar$' } | Select-Object -First 1
+   if (-not $asset) { throw "bundletool release asset not found" }
+   Invoke-WebRequest -Uri $asset.browser_download_url -OutFile "$targetDir\bundletool.jar"
+   $currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+   if ($currentPath -notlike "*$targetDir*") {
+     [Environment]::SetEnvironmentVariable('Path', "$currentPath;$targetDir", 'User')
+   }
+   $env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
+   ```
+
+3. **Validate installation**
+   macOS/Linux:
+   ```bash
+   command -v bundletool.jar
+   java -jar "$(command -v bundletool.jar)" version
+   ```
+   Windows PowerShell:
+   ```powershell
+   $btPath = ($env:Path -split ';' | Where-Object { $_ -and (Test-Path (Join-Path $_ 'bundletool.jar')) } | ForEach-Object { Join-Path $_ 'bundletool.jar' } | Select-Object -First 1)
+   if (-not $btPath) { throw "bundletool.jar not found in PATH directories" }
+   $btPath
+   java -jar $btPath version
+   ```
+
+4. **Report task result**
+   Include:
+   - resolved `bundletool.jar` path
+   - `bundletool` version output
+   - whether installation was skipped because bundletool was already present
+
+## Completion criteria
+Mark complete only when all are true:
+- `bundletool.jar` is resolvable from `PATH`
+- `java -jar <bundletool.jar> version` succeeds
+- result summary states whether install was performed or skipped
+
+## Constraints
+- This is an optional skill; run only when the user explicitly requests bundletool setup.
+- Ask the user before installing optional dependencies.
+- If privileged commands are required, pause and provide exact commands for user execution.
+- Do not modify unrelated Appium, Android SDK, Java, or Xcode configuration in this skill.