@appium/mcp-documentation 1.0.3 → 1.0.4

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

@@ -0,0 +1,260 @@
+---
+name: "environment-setup-chromium"
+description: "Set up and validate an Appium Chromium Driver environment"
+metadata:
+   last_modified: "Thu, 09 Apr 2026 00:00:00 GMT"
+
+---
+# appium-chromium-environment-setup
+
+## Goal
+Prepares a reliable Appium Chromium Driver environment by validating Node.js/npm, ensuring Appium 3 compatibility, installing the Chromium driver, validating browser/runtime prerequisites, and running a smoke test that confirms driver availability and server readiness.
+
+## Decision Logic
+- If the host OS is not macOS, Linux, or Windows: stop and ask the user to use a supported OS.
+- If current Node.js does not satisfy `engines.node` for both `appium` and `appium-chromium-driver`: install/upgrade Node.js to a compatible active LTS version.
+- If current npm does not satisfy `appium-chromium-driver` `engines.npm`: upgrade npm before continuing.
+- If Appium CLI is not installed: install `appium` globally.
+- Use global npm/Appium commands by default (`npm install -g appium`, `appium ...`).
+- Use local Appium commands (`npx appium ...`) only when the user explicitly requests local execution.
+- If Appium major version is `< 3`: upgrade Appium to 3.x before installing or validating `chromium`.
+- If the `chromium` driver is not installed: install it via Appium CLI.
+- If install returns "already installed", ignore the error and continue (or run driver update).
+- If `appium driver doctor chromium` is supported and reports required fixes: resolve each required item and re-run doctor.
+- If doctor is not supported for `chromium` in the active Appium/driver version: use install/list/smoke checks as the completion gate.
+- If no supported Chromium-based browser is available (`chrome`/`chromium`/`msedge`): pause and ask the user which browser to automate and install.
+- If no supported Chromium-based browser is available and the user explicitly approves optional browser setup: install Chrome or Chromium with OS-native package tooling, then re-run browser availability checks.
+- If running inside WSL and browser install is requested: prefer distro package-manager installation as root in WSL (for example via `wsl -u root`) rather than user-space `.deb` extraction, because runtime shared-library dependencies are otherwise easy to miss.
+- If Chrome is present but fails to start with missing shared libraries (for example `libnspr4.so`): treat this as an incomplete Linux dependency install and fix with package-manager dependencies before continuing.
+- If the user does not request a pinned chromedriver version and no chromedriver binary is present in the environment: run `appium driver run chromium install-chromedriver` before smoke validation.
+- If the user explicitly targets Microsoft Edge: treat `msedgedriver` setup as a separate optional step, require a driver version matching the installed Edge build, and pass it through `appium:executable` because automatic chromedriver download does not cover Edge.
+
+## Instructions
+1. **Prepare Node.js + npm environment**
+   macOS/Linux:
+   ```bash
+   node -v
+   npm -v
+   ```
+   Windows PowerShell:
+   ```powershell
+   node -v
+   npm -v
+   ```
+   If `node` is missing, run `environment-setup-node` first (including Windows PowerShell profile bootstrap), then open a new terminal or run `. $PROFILE`, and re-run the commands.
+
+2. **Install/upgrade Appium and Chromium driver**
+   ```bash
+   npm install -g appium@latest
+   appium driver install chromium || appium driver update chromium
+   appium driver list --installed --json || appium driver list --installed
+   ```
+   Prefer `--json` output for machine-readable verification. Confirm a `chromium` key is present; only fallback to plain-text output when `--json` is unsupported.
+   If the install command fails only because `chromium` is already installed, continue and do not stop preparation.
+
+3. **Validate Appium command health and compatibility**
+   macOS/Linux:
+   ```bash
+   appium -v
+   appium driver list --installed --json || appium driver list --installed
+   npm view appium engines --json
+   npm view appium-chromium-driver engines peerDependencies --json
+   ```
+   Windows PowerShell:
+   ```powershell
+   appium -v
+   appium driver list --installed --json; if ($LASTEXITCODE -ne 0) { appium driver list --installed }
+   npm view appium engines --json
+   npm view appium-chromium-driver engines peerDependencies --json
+   ```
+   Verify Appium major version is `3` and that active Node/npm versions satisfy the reported ranges.
+
+4. **Validate browser availability (Chrome/Chromium/Edge)**
+   macOS/Linux:
+   ```bash
+   command -v google-chrome || true
+   command -v chromium || true
+   command -v chromium-browser || true
+   command -v msedge || true
+   ```
+   Windows PowerShell:
+   ```powershell
+   Get-Command chrome.exe -ErrorAction SilentlyContinue
+   Get-Command msedge.exe -ErrorAction SilentlyContinue
+   ```
+   Confirm at least one Chromium-based browser is available and note the target browser in the result summary.
+
+   Optional browser setup (run only when the user explicitly requests it):
+   - macOS (Homebrew):
+   ```bash
+   brew install --cask google-chrome
+   # or
+   brew install --cask chromium
+   # or
+   brew install --cask microsoft-edge
+   ```
+   - Linux (Debian/Ubuntu examples):
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y chromium-browser || sudo apt-get install -y chromium
+   # Microsoft Edge example
+   curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
+   sudo install -o root -g root -m 644 microsoft.gpg /usr/share/keyrings/microsoft.gpg
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/edge stable main" | sudo tee /etc/apt/sources.list.d/microsoft-edge.list
+   sudo apt-get update
+   sudo apt-get install -y microsoft-edge-stable
+   ```
+   - WSL from Windows host (Debian/Ubuntu examples, no interactive sudo prompt):
+   ```powershell
+   wsl -u root -e bash -lc "apt-get update"
+   wsl -u root -e bash -lc "apt-get install -y libnspr4 libnss3 libxss1 libasound2t64 libatk-bridge2.0-0 libatk1.0-0 libcups2t64 libdrm2 libgbm1 libgtk-3-0 xdg-utils"
+   wsl -u root -e bash -lc "apt-get install -y google-chrome-stable || apt-get install -y chromium-browser || apt-get install -y chromium"
+   ```
+   - Windows PowerShell (winget):
+   ```powershell
+   winget install --id Google.Chrome --exact --accept-source-agreements --accept-package-agreements
+   # or
+   winget install --id Hibbiki.Chromium --exact --accept-source-agreements --accept-package-agreements
+   # or
+   winget install --id Microsoft.Edge --exact --accept-source-agreements --accept-package-agreements
+   ```
+   After installation, re-run the browser availability checks in this step.
+
+5. **Install chromedriver when missing (default) or pin it (on request)**
+   If the user does not request a specific chromedriver version, first check whether a chromedriver binary is available:
+   macOS/Linux:
+   ```bash
+   command -v chromedriver || true
+   ```
+   Windows PowerShell:
+   ```powershell
+   Get-Command chromedriver.exe -ErrorAction SilentlyContinue
+   ```
+   If no chromedriver binary is found, run:
+   ```bash
+   appium driver run chromium install-chromedriver
+   ```
+   Use version/directory pinning only when the user explicitly requests manual pinning or mirrored download flows.
+   macOS/Linux examples:
+   ```bash
+   CHROMEDRIVER_VERSION=131.0.6778.3 appium driver run chromium install-chromedriver
+   CHROMEDRIVER_EXECUTABLE_DIR=/path/to/dir appium driver run chromium install-chromedriver
+   ```
+   Windows PowerShell examples:
+   ```powershell
+   $env:CHROMEDRIVER_VERSION='131.0.6778.3'; appium driver run chromium install-chromedriver; Remove-Item Env:\CHROMEDRIVER_VERSION
+   $env:CHROMEDRIVER_EXECUTABLE_DIR='C:\path\to\folder'; appium driver run chromium install-chromedriver; Remove-Item Env:\CHROMEDRIVER_EXECUTABLE_DIR
+   ```
+
+   Optional Edge WebDriver setup (run only when the user explicitly requests Microsoft Edge automation):
+   - Appium Chromium Driver does not autodownload `msedgedriver`.
+   - Download the Microsoft Edge WebDriver version matching the installed Edge build from the official Microsoft Edge WebDriver page:
+       `https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/`
+   - Verify the installed Edge version first:
+   macOS:
+   ```bash
+   defaults read "/Applications/Microsoft Edge.app/Contents/Info" CFBundleShortVersionString
+   ```
+   Linux:
+   ```bash
+   microsoft-edge --version
+   ```
+   Windows PowerShell:
+   ```powershell
+   (Get-Item "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe").VersionInfo.ProductVersion
+   ```
+   - After downloading and extracting `msedgedriver`, place it in a stable path and confirm it works:
+   macOS/Linux:
+   ```bash
+   chmod +x /path/to/msedgedriver
+   /path/to/msedgedriver --version
+   ```
+   Windows PowerShell:
+   ```powershell
+   & "C:\path\to\msedgedriver.exe" --version
+   ```
+   - For Edge sessions, pass the absolute driver path through capabilities:
+   ```json
+   {
+      "platformName": "macOS",
+      "browserName": "MicrosoftEdge",
+      "appium:automationName": "Chromium",
+      "appium:executable": "/absolute/path/to/msedgedriver"
+   }
+   ```
+
+6. **Run Appium doctor for Chromium when supported**
+   ```bash
+   appium driver doctor chromium
+   ```
+   Use `0 required fixes needed` as the pass/fail gate when doctor is supported. Optional warnings are non-blocking. If required fixes remain, apply targeted fixes and re-run.
+   If command output indicates the driver does not expose doctor checks, mark doctor as `not-supported` and continue with install/list/smoke checks.
+
+7. **Start Appium server smoke test**
+   ```bash
+   appium server
+   ```
+   Windows PowerShell recommended form (for deterministic log checks):
+   ```powershell
+   appium server --log "$env:TEMP\appium-chromium-smoke.log" --log-level info
+   ```
+   Keep this server process running in Terminal A.
+
+   In Terminal B, run:
+   ```bash
+   curl -s http://127.0.0.1:4723/status
+   ```
+   First confirm `/status` responds successfully.
+
+   Then confirm startup/readiness from server logs and ensure the `Available drivers:` block contains `chromium` (for example: `- chromium@<version> (automationName 'Chromium')`).
+   If startup banner logs are not available in your terminal integration, use this fallback verification path:
+   - `appium driver list --installed --json` includes `chromium`
+   - `/status` reports server readiness
+
+   After smoke validation, clean up the running Appium server:
+   - In Terminal A, stop the server with `Ctrl+C`.
+   - Verify no leftover Appium server process (Terminal B, macOS/Linux):
+   ```bash
+   pgrep -fl "appium.*server" || echo "no appium server process"
+   ```
+   If `pgrep` output appears to match only the check command itself, run a stricter verification:
+   ```bash
+   if ps -C node -o pid=,args= | grep -E 'appium.*server' > /dev/null; then
+      ps -C node -o pid=,args= | grep -E 'appium.*server'
+   else
+      echo "no appium server process"
+   fi
+   ```
+   - Verify no leftover Appium server process (Terminal B, Windows PowerShell):
+   ```powershell
+   if (Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' }) {
+      Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' } | Select-Object ProcessId, Name, CommandLine
+   } else {
+      "no appium server process"
+   }
+   ```
+
+8. **Agent completion criteria**
+   Mark the skill complete only when all are true:
+   - `appium driver list --installed --json` includes `chromium` (fallback to `appium driver list --installed` if `--json` is unsupported)
+   - `appium -v` succeeds and is Appium 3.x
+   - active Node/npm versions satisfy `appium` and `appium-chromium-driver` engines
+   - if supported, `appium driver doctor chromium` reports `0 required fixes needed` (optional warnings are allowed)
+   - if unsupported, result explicitly marks doctor status as `not-supported`
+   - if no chromedriver binary was present initially and no pinned version was requested, task result includes successful execution of `appium driver run chromium install-chromedriver`
+   - if Microsoft Edge automation was explicitly requested, task result includes installed Edge version, `msedgedriver --version` output, and the absolute path intended for `appium:executable`
+   - task result includes browser availability check and the selected browser target (`chrome`, `chromium`, or `msedge`)
+   - if optional browser setup was requested, task result includes browser install command(s) used and the post-install browser detection output
+   - `/status` check returns a successful status response (`curl` on macOS/Linux, `Invoke-RestMethod` retry loop recommended on Windows)
+   - Appium server logs show startup/readiness successfully after the status check, or readiness is confirmed by `/status` plus JSON driver listing that includes `chromium`
+   - if logs are available, `Available drivers:` includes a `chromium` entry
+   - Appium smoke-test server process is cleanly stopped after validation
+
+## Constraints
+- Use global npm/Appium commands as the default execution mode.
+- Use `npx appium` only if the user explicitly asks for local execution.
+- Treat optional doctor warnings as non-blocking.
+- Ask before installing optional dependencies or browser packages.
+- Prefer deterministic CLI checks over assumptions.
+- If elevated privileges are required, pause and provide exact commands for the user to run.
+- Do not claim success until compatibility checks and smoke-test checks are green.

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

@@ -0,0 +1,216 @@
+---
+name: "environment-setup-espresso"
+description: "Set up and validate an Espresso Appium environment on Android"
+metadata:
+   last_modified: "Mon, 06 Apr 2026 00:00:00 GMT"
+
+---
+# appium-espresso-environment-setup
+
+## Goal
+Prepares a reliable Appium Espresso execution environment by installing Node.js and Appium prerequisites, configuring Android and Java dependencies, running Appium doctor checks, and iterating until doctor reports `0 required fixes needed`.
+
+## Decision Logic
+- If the host OS is not macOS, Linux, or Windows: stop and ask the user to use a supported OS.
+- If current Node.js does not satisfy `engines.node` for both `appium` and `appium-espresso-driver`: install/upgrade Node.js to a compatible active LTS version.
+- If Appium CLI is not installed: install `appium` globally.
+- Use global npm/Appium commands by default (`npm install -g appium`, `appium ...`).
+- Use local Appium commands (`npx appium ...`) only when the user explicitly requests local execution.
+- If Android SDK prerequisites are missing (`adb`, emulator binary, SDK packages): run `environment-setup-android` first.
+- If the user explicitly requests media features that require FFmpeg: run `environment-setup-ffmpeg` before final validation.
+- If the user explicitly requests automatic bundletool setup: run `environment-setup-bundletool` before final validation.
+- Always include host device/emulator inventory in the final skill result (connected devices, emulator version, and AVD list).
+- If the `espresso` driver is not installed: install it via Appium CLI.
+- If install returns "already installed", ignore the error and continue (or run driver update).
+- If `appium driver doctor espresso` reports missing dependencies: resolve each missing item and re-run doctor.
+
+## Instructions
+1. **Prepare Node.js + npm environment**
+   macOS/Linux:
+   ```bash
+   node -v
+   npm -v
+   ```
+   Windows PowerShell:
+   ```powershell
+   node -v
+   npm -v
+   ```
+   If `node` is missing, run `environment-setup-node` first (including Windows PowerShell profile bootstrap), then open a new terminal or run `. $PROFILE`, and re-run the commands.
+   Windows PowerShell session bootstrap (recommended before any `appium` command in fresh/background terminals):
+   ```powershell
+   $fnmDir = "$env:LOCALAPPDATA\Microsoft\WinGet\Packages\Schniz.fnm_Microsoft.Winget.Source_8wekyb3d8bbwe"
+   if (Test-Path $fnmDir) { $env:PATH = "$fnmDir;$env:PATH" }
+   fnm env --shell powershell | Invoke-Expression
+   fnm use lts-latest
+   ```
+
+2. **Install Appium npm command**
+   ```bash
+   npm install -g appium
+   appium driver install espresso || appium driver update espresso
+   appium driver list --installed --json || appium driver list --installed
+   ```
+   Prefer `--json` output for machine-readable verification. Confirm an `espresso` key is present; only fallback to plain-text output when `--json` is unsupported.
+   If the install command fails only because `espresso` is already installed, continue and do not stop preparation.
+
+3. **Validate Appium npm commands and Node compatibility (after driver setup)**
+   macOS/Linux:
+   ```bash
+   appium -v
+   appium driver list --installed --json || appium driver list --installed
+   npm view appium engines --json
+   npm view appium-espresso-driver engines --json
+   ```
+   Windows PowerShell:
+   ```powershell
+   appium -v
+   appium driver list --installed --json; if ($LASTEXITCODE -ne 0) { appium driver list --installed }
+   npm view appium engines --json
+   npm view appium-espresso-driver engines --json
+   ```
+   If current Node.js does not satisfy the reported `engines.node` ranges, install/upgrade Node.js to a compatible active LTS version and re-run the setup checks.
+
+4. **Run Android environment prerequisite skill**
+   Before Espresso doctor checks, execute `environment-setup-android` and do not continue until it passes completion criteria.
+
+5. **Verify Android prerequisites from this skill context**
+   macOS/Linux:
+   ```bash
+   command -v adb
+   adb version
+   echo "$ANDROID_HOME"
+   ls "$ANDROID_HOME/emulator/emulator"
+   test -x "$ANDROID_HOME/emulator/emulator" && echo "emulator binary: OK"
+   ```
+   Windows PowerShell:
+   ```powershell
+   Get-Command adb.exe -ErrorAction SilentlyContinue
+   adb.exe version
+   $env:ANDROID_HOME
+   Test-Path "$env:ANDROID_HOME\emulator\emulator.exe"
+   if (Test-Path "$env:ANDROID_HOME\emulator\emulator.exe") { "emulator binary: OK" }
+   ```
+
+6. **Report connected devices and emulator inventory in task result**
+   macOS/Linux:
+   ```bash
+   adb devices -l
+   "$ANDROID_HOME/emulator/emulator" -version
+   "$ANDROID_HOME/emulator/emulator" -list-avds
+   ```
+   Windows PowerShell:
+   ```powershell
+   adb.exe devices -l
+   & "$env:ANDROID_HOME\emulator\emulator.exe" -version
+   & "$env:ANDROID_HOME\emulator\emulator.exe" -list-avds
+   ```
+   In the result summary, explicitly state whether emulator preparation was skipped because either connected devices already existed or one/more AVDs already existed.
+
+   Optional shared dependency:
+   - If the user explicitly requests FFmpeg-related capability, run `environment-setup-ffmpeg` before continuing.
+   - If the user explicitly requests bundletool installation, run `environment-setup-bundletool` before continuing.
+
+7. **Run Appium doctor for Espresso and fix in a loop**
+   ```bash
+   appium driver doctor espresso
+   ```
+   Use `0 required fixes needed` as the pass/fail gate. Optional warnings are non-blocking. If required fixes remain, apply targeted fixes and re-run.
+   For deterministic automation, parse the doctor output for that exact phrase instead of relying on visual formatting.
+   Bash gate example:
+   ```bash
+   DOCTOR_OUT="$(appium driver doctor espresso 2>&1)"
+   echo "$DOCTOR_OUT" | grep -q "0 required fixes needed" || { echo "$DOCTOR_OUT"; exit 1; }
+   echo "$DOCTOR_OUT" | grep -E "0 required fixes needed|optional fix"
+   ```
+   PowerShell gate example:
+   ```powershell
+   $doctorOut = appium driver doctor espresso 2>&1 | Out-String
+   if ($doctorOut -notmatch '0 required fixes needed') { throw "Doctor required fixes remain" }
+   $doctorOut | Select-String '0 required fixes needed|optional fix'
+   ```
+   AI-assisted fallback (only if exact phrase matching is inconclusive due output-format changes):
+   1. Re-run doctor once and capture full output (`appium driver doctor espresso 2>&1 | tee /tmp/appium-doctor-espresso.log`).
+   2. Ask an AI agent to classify required vs optional findings from the captured output.
+   3. Accept a pass only when the output clearly indicates zero required issues (for example: no required-fix section and no required-check failures).
+   4. If still ambiguous, mark status as `needs-manual-review` and do not mark the skill complete.
+
+8. **Start Appium server smoke test**
+   ```bash
+   appium server
+   ```
+   Windows PowerShell recommended form (for deterministic log checks):
+   ```powershell
+   appium server --log "$env:TEMP\appium-espresso-smoke.log" --log-level info
+   ```
+   Keep this server process running in Terminal A.
+   In Terminal B, run:
+   ```bash
+   curl -s http://127.0.0.1:4723/status
+   ```
+   First confirm `/status` responds successfully.
+   Windows PowerShell reliable variant (recommended on Windows due to `curl` alias behavior):
+   ```powershell
+   $ok = $false
+   for ($i = 0; $i -lt 20; $i++) {
+      try {
+         $resp = Invoke-RestMethod -Uri "http://127.0.0.1:4723/status" -Method Get -TimeoutSec 5
+         if ($resp.value.ready -eq $true) {
+            $ok = $true
+            $resp | ConvertTo-Json -Depth 5
+            break
+         }
+      } catch {
+         Start-Sleep -Milliseconds 500
+      }
+   }
+   if (-not $ok) { throw "Appium /status did not become ready in time" }
+   ```
+   Then confirm startup/readiness from server logs and ensure the `Available drivers:` block contains `espresso` (for example: `- espresso@<version> (automationName 'Espresso')`).
+   If startup banner logs are not available in your terminal integration, use this fallback verification path:
+   - `appium driver list --installed --json` includes `espresso`
+   - `/status` reports server readiness
+   Windows PowerShell log verification example:
+   ```powershell
+   Get-Content "$env:TEMP\appium-espresso-smoke.log" | Select-String "listener started|Available drivers:|espresso@"
+   ```
+   After smoke validation, clean up the running Appium server:
+   - In Terminal A, stop the server with `Ctrl+C`.
+   - Verify no leftover Appium server process (Terminal B, macOS/Linux):
+   ```bash
+   pgrep -fl "appium.*server" || echo "no appium server process"
+   ```
+   - Verify no leftover Appium server process (Terminal B, Windows PowerShell):
+   ```powershell
+   if (Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' }) {
+      Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' } | Select-Object ProcessId, Name, CommandLine
+   } else {
+      "no appium server process"
+   }
+   ```
+
+9. **Agent completion criteria**
+   Mark the skill complete only when all are true:
+   - `appium driver list --installed --json` includes `espresso` (fallback to `appium driver list --installed` if `--json` is unsupported)
+   - `appium -v` succeeds
+   - `appium driver doctor espresso` reports `0 required fixes needed` (optional warnings are allowed)
+   - task result includes the doctor summary line with required/optional fix counts
+   - `environment-setup-android` completion criteria are satisfied
+   - task result includes connected-device output (`adb devices -l`) and emulator inventory (`emulator -version`, `emulator -list-avds`)
+   - task result explicitly states whether emulator preparation was skipped (and why)
+   - `/status` check returns a successful status response (`curl` on macOS/Linux, `Invoke-RestMethod` retry loop recommended on Windows)
+   - Appium server logs show startup/readiness successfully after the status check, or (if banner logs are unavailable) readiness is confirmed by `/status` plus JSON driver listing that includes `espresso`
+   - If logs are available, `Available drivers:` includes an `espresso` entry
+   - Appium smoke-test server process is cleanly stopped after validation
+
+## Constraints
+- Always run `appium driver doctor espresso` after each environment change.
+- Use global npm/Appium commands as the default execution mode.
+- Use `npx appium` only if the user explicitly asks for local execution.
+- Do not skip Android prerequisite validation; rely on `environment-setup-android` for source-of-truth checks.
+- Use shell-appropriate commands (`bash` for macOS/Linux, PowerShell/cmd for Windows).
+- Treat optional doctor warnings as non-blocking.
+- Ask the user before installing optional dependencies, and install them only when the user explicitly needs that capability.
+- Prefer deterministic CLI checks over assumptions.
+- If elevated privileges are required, pause and provide exact commands for the user to run.
+- Do not claim success until doctor and smoke-test checks are actually green.

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

@@ -0,0 +1,91 @@
+---
+name: "environment-setup-ffmpeg"
+description: "Install and validate FFmpeg on macOS, Linux, or Windows for optional Appium media capabilities"
+metadata:
+  last_modified: "Mon, 09 Mar 2026 13:10:00 GMT"
+
+---
+# environment-setup-ffmpeg
+
+## Goal
+Installs and validates FFmpeg in a cross-platform way so Appium environments can use optional media-related capabilities when explicitly requested.
+
+## Decision Logic
+- If host OS is unsupported: stop and ask the user to run on macOS, Linux, or Windows.
+- If `ffmpeg` is already available in `PATH`: do not reinstall; only validate version output.
+- If user has not explicitly requested FFmpeg-related capability: skip this skill.
+- If host OS is macOS: prefer Homebrew install.
+- If host OS is Linux: use distro package manager install.
+- If host OS is Windows: prefer `winget`; fallback to Chocolatey if `winget` is unavailable.
+
+## Instructions
+1. **Detect OS and current FFmpeg availability**
+   macOS/Linux:
+   ```bash
+   uname -s
+   command -v ffmpeg || echo "ffmpeg not found"
+   ffmpeg -version || true
+   ```
+   Windows PowerShell:
+   ```powershell
+   [System.Environment]::OSVersion.VersionString
+   Get-Command ffmpeg.exe -ErrorAction SilentlyContinue
+   ffmpeg -version
+   ```
+
+2. **Install FFmpeg when missing**
+   macOS (Homebrew):
+   ```bash
+   brew install ffmpeg
+   ```
+   Linux (Debian/Ubuntu):
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y ffmpeg
+   ```
+   Linux (RHEL/CentOS/Fedora):
+   ```bash
+   sudo dnf install -y ffmpeg
+   ```
+   Linux (Arch):
+   ```bash
+   sudo pacman -S --noconfirm ffmpeg
+   ```
+   Windows PowerShell (`winget` preferred):
+   ```powershell
+   winget install --id Gyan.FFmpeg --exact --accept-package-agreements --accept-source-agreements
+   ```
+   Windows PowerShell (Chocolatey fallback):
+   ```powershell
+   choco install ffmpeg -y
+   ```
+
+3. **Validate installation and PATH**
+   macOS/Linux:
+   ```bash
+   command -v ffmpeg
+   ffmpeg -version
+   ```
+   Windows PowerShell:
+   ```powershell
+   Get-Command ffmpeg.exe -ErrorAction SilentlyContinue
+   ffmpeg -version
+   ```
+
+4. **Report capability in task result**
+   Include:
+   - resolved FFmpeg executable path
+   - first line of `ffmpeg -version`
+   - whether installation was skipped because FFmpeg was already present
+
+## Completion criteria
+Mark complete only when all are true:
+- `ffmpeg` is resolvable from `PATH`
+- `ffmpeg -version` succeeds
+- result summary states whether install was performed or skipped
+
+## Constraints
+- This is an optional skill; run only when the user explicitly requests FFmpeg-related setup.
+- Ask before installing optional dependencies.
+- If privileged commands are required, pause and provide exact commands for user execution.
+- Do not modify unrelated Appium, Java, Android SDK, or Xcode configuration in this skill.