# Setup Gecko

> Prepare and verify Appium Gecko for Firefox desktop automation by validating Node/Appium, Firefox prerequisites, driver installation, optional GeckoDriver availability, doctor support, and server smoke evidence. Use after the setup Skill selects Gecko. Do not use for an existing Gecko runtime failure after prerequisites pass.

- Skill: `appium/setup-gecko` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add appium/setup-gecko`
- Raw SKILL.md: https://api.skillmd.com/api/skills/appium/setup-gecko/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: appium (https://skillmd.com/u/appium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/appium/setup-gecko

---


# Gecko Setup Workflow

## Routing

Prepare only the Appium Gecko route for Firefox desktop browsers. Use
driver-specific official guidance for an existing runtime failure after setup
passes.

## Required inputs

Confirm the Firefox channel or executable when non-default, global `appium`
mode or explicitly requested local `npx appium` mode, host OS, and permissions
for browser or package-manager changes.

## Workflow

1. Load the global command profile by default or the local profile only when
   explicitly requested.
2. Load the Gecko profile, shared Appium setup basics, Firefox prerequisites,
   and Gecko decision, driver-validation, and smoke references.
3. Run `node tools/appium/setup/scripts/check-gecko-env.mjs --format summary --report auto`; add
   `--appium-mode local` only for explicitly requested local mode. Require
   top-level `summary.requiredOk: true`.
   Apply required fixes in technical dependency order and rerun affected checks.
   If the gate remains unresolved, report `blocked` with evidence and the next
   action. Load the matching example only when needed.
4. Verify `appium driver doctor gecko` reports `0 required fixes needed`, or
   record `not-supported` and require the install, list, Firefox, and smoke
   gates instead. Use `npx --no-install appium ...` for the direct check in
   local mode.
5. Run `node tools/appium/setup/scripts/smoke-appium-server.mjs --driver gecko --report auto`;
   add `--appium-mode local` only in local mode. Require
   `summary.requiredOk: true` for server readiness, driver evidence, and
   cleanup. The smoke reference documents target-specific options.

## Gecko setup safety and approval constraints

- Ask before privileged package-manager commands or browser installation.
- Install an optional Firefox channel only when explicitly requested;
  otherwise use an existing supported Firefox installation or report it
  missing.
- Preserve the selected command mode and working Firefox and driver
  installations.

## Completion criteria

- Appium succeeds in the selected command mode with major version `>= 3`.
- The installed driver list includes `gecko`.
- At least one supported Firefox browser is available.
- Doctor reports `0 required fixes needed` when supported; otherwise the
  install, list, Firefox, and smoke gates pass.
- `/status` succeeds and logs list `gecko`.

## Evidence boundary

Report Appium and driver versions, Firefox executable and channel, helper and
doctor summaries, `/status`, server driver evidence, and cleanup.

## Self-Improvement Prompt

Before the final response, report any missing, ambiguous, outdated, or
retry-causing Gecko setup instruction with its asset path and proposed wording.
Leave unrelated assets unchanged.