feat: add Appium troubleshooting skill

AGENTS.md

@@ -49,6 +49,11 @@ This file defines how AI agents should execute the skills in this repository.
 2. `environment-setup-xcuitest`
 3. `xcuitest-real-device-config`
 
+### Troubleshooting
+
+1. If prerequisites or doctor checks are failing, run the relevant environment setup skill first.
+2. Then run `appium-troubleshooting` in the failing driver path and load only the platform reference files that match the symptom.
+
 ## Completion Policy
 
 A skill is complete only when its own completion criteria in `SKILL.md` are satisfied.
@@ -153,6 +158,26 @@ Rules:
   4) At least one WDA deployment method is confirmed working (default xcodebuild, preinstalled, prebuilt, or attach).
 ```
 
+### Template: Troubleshooting
+
+Use this as a starting prompt for an AI agent:
+
+```text
+Use this repository's troubleshooting skill to diagnose an Appium failure.
+Follow this order:
+1) If setup or doctor output is failing, run the matching environment setup skill first.
+2) skills/appium-troubleshooting/SKILL.md
+
+Rules:
+- Run one step at a time.
+- Keep troubleshooting scoped to the failing driver unless the user explicitly asks for cross-driver comparison.
+- Re-run the smallest failing check after each fix.
+- Treat Appium doctor required fixes as blocking.
+- Prefer the official Appium references bundled with the troubleshooting skill before using discuss.appium.io.
+- Use discuss.appium.io only when the official references do not explain the exact stack trace or symptom.
+- Show command output for each step.
+```
+
 ## Notes for Tooling Integrations
 
 - If your agent platform supports repository-level instruction files, prioritize this file before running skill commands.

README.md

@@ -1,6 +1,6 @@
 # Appium Agent Skills
 
-This repository contains AI Agent skills for helping with Appium automation.
+This repository contains AI Agent skills for helping with Appium automation, including environment setup, real-device configuration, and troubleshooting common failures.
 
 ## Available Skills
 
@@ -13,6 +13,7 @@ This repository contains AI Agent skills for helping with Appium automation.
 | [environment-setup-uiautomator2](skills/environment-setup-uiautomator2/SKILL.md) | Prepares and validates an Android + UiAutomator2 Appium environment |
 | [environment-setup-espresso](skills/environment-setup-espresso/SKILL.md) | Prepares and validates an Android + Espresso Appium environment |
 | [environment-setup-xcuitest](skills/environment-setup-xcuitest/SKILL.md) | Prepares and validates a macOS + XCUITest Appium environment |
+| [appium-troubleshooting](skills/appium-troubleshooting/SKILL.md) | Troubleshoots UiAutomator2 or XCUITest failures with a driver-scoped workflow that starts from the failing symptom and re-checks the smallest reproduction after each fix |
 | [xcuitest-real-device-config](skills/xcuitest-real-device-config/SKILL.md) | Prepare a real iOS/tvOS device for Appium XCUITest automation |
 
 ## Reliable Execution Notes
@@ -23,8 +24,9 @@ This repository contains AI Agent skills for helping with Appium automation.
 - Treat Appium doctor as the source of truth for pass/fail (`0 required fixes needed`).
 - For FFmpeg-dependent capabilities, run the optional shared skill `environment-setup-ffmpeg` only when explicitly requested.
 - For bundletool-dependent capabilities, run the optional shared skill `environment-setup-bundletool` only when explicitly requested.
+- For startup, WDA, or locator failures after setup is complete, use `appium-troubleshooting` in a single driver path and follow the checks documented in that skill.
 
 ## Agent Instructions
 
 - See [AGENTS.md](AGENTS.md) for strict execution rules and copy-paste prompt templates.
-- Use the template matching your target (`uiautomator2`, `espresso`, or `xcuitest`) and run skills in the documented order.
+- Use the template matching your target (`uiautomator2`, `espresso`, `xcuitest`, `xcuitest real device`, or `troubleshooting`) and run skills in the documented order.

skills/appium-troubleshooting/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: "appium-troubleshooting"
+description: "Diagnose common Appium failures with a driver-scoped flow for UiAutomator2 or XCUITest, covering startup, driver readiness, WebDriverAgent, and element lookup issues"
+metadata:
+  last_modified: "Thu, 19 Mar 2026 12:00:00 GMT"
+
+---
+# appium-troubleshooting
+
+## Goal
+Help the agent narrow a single-driver Appium failure into a small set of common buckets, apply the smallest plausible fix, and re-run the failing check until the root cause is confirmed or clearly handed back to the user.
+
+## Decision Logic
+- Identify the active automation driver first (`uiautomator2` or `xcuitest`). If unknown, stop and ask for the failing session capabilities/log line that names the driver.
+- If the failure is an environment or driver-install problem (`node`, `npm`, `appium`, Java, Android SDK, `Xcode`, doctor failures): run the matching setup skill for the selected driver first.
+- UiAutomator2 path only:
+  - session startup, wrong activity, early drop, or `socket hang up`: read [references/uiautomator2-session-startup.md](references/uiautomator2-session-startup.md).
+  - locator issues: read [references/uiautomator2-locators.md](references/uiautomator2-locators.md).
+- XCUITest path only:
+  - WebDriverAgent startup/install/reachability, app install/launch, device/simulator state: read [references/xcuitest-troubleshooting.md](references/xcuitest-troubleshooting.md).
+  - element lookup or locator issues: read [references/xcuitest-element-lookup.md](references/xcuitest-element-lookup.md) and [references/xcuitest-locators.md](references/xcuitest-locators.md).
+- If the official docs do not explain the exact stack trace or symptom, use [references/community-search.md](references/community-search.md) as a fallback workflow.
+
+## Instructions
+1. **Capture the failing command and lock the driver scope**
+   Record the exact error text, platform, automation driver, and relevant capabilities before changing anything. If the driver is still unclear, ask for one of these before continuing:
+   - the desired capabilities block containing `platformName` and `appium:automationName`
+   - the Appium server log lines from `POST /session` through the first real error after `createSession`
+   If the client hides capabilities, rerun one failing session with Appium server logs enabled and capture that window before troubleshooting further.
+
+2. **Run baseline checks only when the error message alone is not enough**
+   If the error text already points to a known issue, open the matching driver-specific official reference first and confirm the closest symptom before changing anything. Then collect what is needed:
+   - `appium -v` and `appium driver list --installed` — to confirm driver presence and version.
+   - UiAutomator2: `adb devices -l` and `appium driver doctor uiautomator2` — only if the error suggests a device connectivity or prerequisite problem.
+   - XCUITest: `xcodebuild -version` and `appium driver doctor xcuitest` — only if the error suggests a build, signing, or toolchain problem.
+   If any doctor or prerequisite check fails, switch to the matching setup skill before deeper troubleshooting. Use `references/community-search.md` only after the relevant official reference does not explain the exact stack trace or symptom.
+
+3. **Open only the references that match the selected driver and symptom**
+   Do not load both driver branches in one run. Start with the most direct reference for the observed symptom and only expand if that file does not explain the behavior.
+
+4. **Apply one targeted change, then re-run the smallest failing check**
+   Prefer narrow fixes such as capability corrections, driver cleanup, device reset, or locator updates before broader environment churn. Re-run the doctor command for prerequisite issues, the failing session launch for startup issues, or the failing locator lookup for element issues.
+
+5. **Use official docs first, community second**
+   Official references for this skill:
+   - `https://appium.io/docs/en/latest/`
+   - `https://github.com/appium/appium-uiautomator2-driver`
+   - `https://appium.github.io/appium-xcuitest-driver/latest/`
+   - `https://github.com/appium/appium-xcuitest-driver`
+   Use `discuss.appium.io` only after the official references are exhausted, searching with exact error text plus driver name and platform version.
+
+6. **Report the outcome with command evidence**
+   Include the baseline checks you ran, the change you made, and the smallest reproduction or check you re-ran to confirm the result.
+
+## Completion Criteria
+Mark troubleshooting complete only when one of these is true:
+- the failing check passes after a verified fix, or
+- the exact blocker is isolated to something the user must do manually (for example signing, device trust, app build defects), with the relevant command output and next action captured
+
+## Constraints
+- Run commands one step at a time and re-run checks after each fix.
+- Treat Appium doctor required fixes as blocking.
+- Use global `appium` command mode by default unless the user explicitly asks for local `npx appium`.
+- Prefer the official Appium driver docs referenced by this skill before using community answers.
+- Keep troubleshooting scoped to one driver path (`uiautomator2` or `xcuitest`) per run unless the user explicitly asks for cross-driver comparison.
+- Do not claim success from a theory alone; always tie the conclusion to a reproduced symptom or a passing re-check.

skills/appium-troubleshooting/references/community-search.md

@@ -0,0 +1,51 @@
+# Community Search Fallback
+
+## Source
+- `https://discuss.appium.io/`
+
+## Official-First Rule
+Use community search only after checking the matching official Appium reference first:
+
+- UiAutomator2 startup: `https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/activity-startup.md`
+- UiAutomator2 locators: `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#element-location`
+- XCUITest element lookup: `https://appium.github.io/appium-xcuitest-driver/latest/guides/elements-lookup-troubleshooting/`
+- XCUITest locators: `https://appium.github.io/appium-xcuitest-driver/latest/reference/locator-strategies/`
+- XCUITest general failures: `https://appium.github.io/appium-xcuitest-driver/latest/guides/troubleshooting/`
+
+## Search Pattern
+- Search the exact error string in quotes.
+- Add the driver name: `uiautomator2` or `xcuitest`.
+- Add the platform version and whether the target is a real device or simulator/emulator.
+- Add the capability name if the issue appears right after changing one capability.
+
+Example queries:
+- `"socket hang up" uiautomator2 Android 14 emulator`
+- `"Activity never started" appWaitActivity uiautomator2`
+- `"WebDriverAgent" xcuitest iOS 18 real device`
+- `"No matches found for Identity Binding" xcuitest`
+
+## Offline Triage Before Searching
+
+Use one of these recurring cases to choose a search query and one local verification step. Keep the detailed remediation in the official references whenever possible.
+
+| Case | Search Query Seed | Verify First |
+|---|---|---|
+| UiAutomator2 wrong startup screen or `Activity never started` | `"Activity never started" appWaitActivity uiautomator2` | confirm the focused activity via `adb shell dumpsys activity activities` |
+| UiAutomator2 early session drop or `socket hang up` | `"socket hang up" uiautomator2 <android-version> <device-type>` | capture `adb logcat -d` and retry one clean session |
+| UiAutomator2 WebView or Chromedriver mismatch | `"chromedriver" uiautomator2 webview` | confirm the WebView/browser version on the device before changing Chromedriver settings |
+| XCUITest WDA build or signing failure | `"WebDriverAgent" "xcodebuild" failed xcuitest` | run `appium driver doctor xcuitest` and verify the signing setup |
+| XCUITest WDA timeout or proxy failure | `"Could not proxy command to remote server" xcuitest` | capture fresh Appium logs and confirm WDA reachability |
+| XCUITest source tree incomplete or element missing | `"elements not visible in source" xcuitest inspector` | collect a fresh source snapshot and verify accessibility exposure or active context |
+
+## How To Filter Results
+- Prefer threads that mention the same Appium major version and the same driver.
+- Prefer posts that include logs or cite official Appium docs.
+- Treat advice that suggests broad resets or unrelated capability changes as low confidence until you can verify it locally.
+
+## Accept/Reject Rule For Forum Advice
+- Accept only if the suggestion maps directly to your exact error text, same driver, and similar OS/device version.
+- Reject or defer suggestions that require unrelated global resets before reproducing the same failure once.
+- Always re-run the smallest failing check immediately after applying a proposed fix.
+
+## Validation Rule
+Never close the issue from a forum answer alone. Reproduce the proposed fix locally and tie it back to the original failing command or locator.

skills/appium-troubleshooting/references/uiautomator2-locators.md

@@ -0,0 +1,34 @@
+# UiAutomator2 Locators
+
+## Official Reference
+- `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#element-location`
+
+Use the driver docs for the full strategy list and performance tradeoffs. Keep this page for the extra triage that is easy to miss during debugging.
+
+## Local Guidance
+- Inspect the current page source before changing the selector. Verify whether the target is exposed as `content-desc`, resource id, text, or only as a visual label.
+- If the app is hybrid, confirm the current context before debugging native locators.
+- `-android uiautomator` is useful when ids or accessibility metadata are missing, but keep the query narrow and readable enough to debug from logs.
+- Treat a working `xpath` as proof that the node exists, not as the preferred final fix. Replace it with a stronger native locator when the source exposes one.
+- If the node is not present in source at all, this is usually an app-state, accessibility, or context problem rather than locator syntax.
+
+## Hybrid App Checks
+- If the element is inside a WebView, confirm the failing lookup is happening in a `WEBVIEW_*` context rather than `NATIVE_APP`.
+- If the failure started after a Chrome or Android System WebView update, confirm the WebView/browser version before changing Chromedriver settings.
+- Use the UiAutomator2 driver's Chromedriver compatibility guidance before community fallback. Prefer `appium:chromedriverExecutable`, `appium:chromedriverExecutableDir`, or automatic Chromedriver discovery over ad hoc workarounds.
+- If the node exists only in the WebView DOM and not in native page source, switch context first and re-run the same single lookup before changing selectors.
+
+## Hybrid App Checks With Commands
+```bash
+adb shell dumpsys package com.android.chrome | grep versionName
+adb shell dumpsys package com.google.android.webview | grep versionName
+adb shell dumpsys package com.android.webview | grep versionName
+```
+- Capture the current context list from the failing client run and confirm the target lookup is using the expected `WEBVIEW_*` context.
+- Capture one source snapshot from `NATIVE_APP` and one from the target `WEBVIEW_*` context on the same screen. If the element appears only in the WebView DOM, switch context before changing selectors.
+- If Chromedriver is the likely mismatch, prefer updating `appium:chromedriverExecutable`, `appium:chromedriverExecutableDir`, or the Chromedriver mapping instead of rewriting the locator first.
+
+## Validation
+- Re-run the smallest failing lookup.
+- Compare the returned attributes against the actual source dump.
+- If an `xpath` fix works but a stronger native locator is available, prefer the native locator before closing the issue.

skills/appium-troubleshooting/references/uiautomator2-session-startup.md

@@ -0,0 +1,53 @@
+# UiAutomator2 Session Startup
+
+## Official References
+- `https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/activity-startup.md`
+- `https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#troubleshooting`
+
+## When To Read This
+- `Activity never started`
+- app launches the wrong screen or splash flow
+- `appWaitActivity` or `appWaitPackage` mismatches
+- `socket hang up`
+- the UiAutomator2 server appears to die during startup
+
+This file is a shortcut into the official driver docs, not a replacement for them.
+
+## Local Triage
+1. Verify the package and foreground activity from the device state, not from the manifest guess.
+2. Align `appium:appPackage`, `appium:appActivity`, `appium:appWaitPackage`, and `appium:appWaitActivity` with the observed startup flow.
+3. If the app legitimately passes through multiple transient activities, list those wait activities explicitly before increasing `appium:appWaitDuration`.
+4. If logs show `socket hang up`, instrumentation failure, or helper-package errors, treat it as a UiAutomator2 helper or `adb` transport problem first.
+5. If logs show install, ABI, permission, or signing failures, stop tuning startup capabilities and fix that underlying failure first.
+
+## Log Clues To Separate Common Causes
+- Activity mismatch is more likely if `adb shell dumpsys activity activities` shows a different foreground activity than the one implied by `appium:appActivity` or `appium:appWaitActivity`, or if Appium reports `Activity never started`.
+- A UiAutomator2 server crash is more likely if `adb logcat -d` shows instrumentation failure, `io.appium.uiautomator2.server` package errors, or the Appium log says it cannot connect to the UiAutomator2 REST server.
+- An `adb` transport drop is more likely if the device disappears from `adb devices -l`, the Appium log shows proxy/connectivity resets, or multiple commands fail immediately after `adb` communication errors.
+
+## Minimal Checks
+```bash
+adb shell dumpsys window windows
+adb shell dumpsys activity activities
+adb shell pm list packages
+adb logcat -d
+grep -i "socket hang up\|uiautomator2\|instrumentation\|adb\|cannot connect" <appium-server-log-file>
+```
+
+## First Pass Order
+1. Capture `dumpsys activity`, `adb logcat -d`, and the matching Appium server log lines from the failing session.
+2. Decide whether the first failure signal is activity mismatch, UiAutomator2 server crash, or `adb` transport loss.
+3. Apply only the fix for that first signal.
+4. Re-run one fresh session start before changing anything else.
+
+## One Clean Retry
+If startup still dies early after the first log review, do one clean retry:
+
+```bash
+adb kill-server
+adb start-server
+adb uninstall io.appium.uiautomator2.server
+adb uninstall io.appium.uiautomator2.server.test
+```
+
+Then re-run the same single session launch and compare fresh logs before changing anything else.

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.