From fc922ab9d27120f3fc22950182d09e0e13ac2288 Mon Sep 17 00:00:00 2001 From: guo-feng-rui Date: Tue, 26 May 2026 17:53:23 -0400 Subject: [PATCH] docs(skill): make Firefox install instruction portable + add agent-facing preflight check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Prerequisites section told users to run "playwright install firefox", but the bare "playwright" console script is not on PATH for a number of common install paths — notably Windows Store Python, fresh `pip install --user` installs, and bare virtualenvs whose Scripts/ directory isn't shimmed. On those setups the documented command fails with "playwright: command not found" before the user can do anything. This change: - Switches the install command to `python -m playwright install firefox`, which is the official-equivalent invocation and resolves uniformly across Windows, macOS, Linux, virtualenvs, and Windows Store Python. - Adds a small preflight one-liner the agent (or user) can run before the first heredoc: it imports playwright, checks whether `firefox.executable_path` actually exists on disk, and prints `FIREFOX_READY` or `NEEDS_INSTALL`. This catches the surprising failure mode where `pip install playwright` populates `executable_path` to a versioned dir (e.g. `firefox-1509/...`) but the binary at that path isn't downloaded until the install step, which leads to `BrowserType.launch: Executable doesn't exist at ...` for the first heredoc. - Keeps the section short — no new code in any of the heredoc patterns, no new dependencies. Verified the preflight one-liner on Windows 11 + Python 3.12: prints `FIREFOX_READY` when Firefox is installed and `NEEDS_INSTALL` when the versioned firefox dir is empty. --- skills/webwright/SKILL.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/skills/webwright/SKILL.md b/skills/webwright/SKILL.md index c70e23c..cf923e0 100644 --- a/skills/webwright/SKILL.md +++ b/skills/webwright/SKILL.md @@ -34,12 +34,31 @@ own native abilities**: you read PNGs with `Read` and verify success against ## Prerequisites (one-time) -From the Webwright repo root: +Install the Playwright Firefox browser binary once before the first task. +Use the `python -m` invocation so the same line works on Windows / +Windows Store Python and inside virtualenvs where the standalone +`playwright` console script is not necessarily on `PATH`: ```bash -playwright install firefox +python -m playwright install firefox ``` +**Preflight check (recommended before the first heredoc).** Playwright's +`firefox.executable_path` resolves to a versioned path +(`firefox-/...`) the moment `pip install playwright` runs, but the +binary at that path doesn't actually exist until you run the install +command above. Running a Playwright heredoc against the missing binary +fails with `BrowserType.launch: Executable doesn't exist at `. +To detect the state deterministically: + +```bash +python -c "import pathlib; from playwright.sync_api import sync_playwright; p=sync_playwright().start(); ok=pathlib.Path(p.firefox.executable_path).exists(); p.stop(); print('FIREFOX_READY' if ok else 'NEEDS_INSTALL')" +``` + +If the agent sees `NEEDS_INSTALL`, run `python -m playwright install firefox` +before proceeding. The check is cheap (a few hundred ms) and the install +itself is a one-time ~110 MB download. + No API keys needed for this skill. ## Workspace Contract