docs(skill): portable Firefox install command + agent-facing preflight check

[raykuo998]

Summary

The Prerequisites section of skills/webwright/SKILL.md instructs the user to run playwright install firefox. On a number of common Python setups the bare playwright console script is not on PATH:

• Windows Store Python (the default Python 3.x install on Windows 10/11)
• Fresh pip install --user installs where ~/AppData/Roaming/Python/Python<ver>/Scripts (Windows) or ~/.local/bin (POSIX) is not in the user's shell PATH
• Bare virtualenvs whose Scripts/ directory isn't shimmed by the shell

On those setups the documented command fails with playwright: command not found before the user can do anything. Hit on a stock Windows 11 + Python 3.12 (Windows Store) install while running through Webwright's own SKILL onboarding flow.

There's a second, more subtle friction: the moment pip install playwright runs, playwright.firefox.executable_path resolves to a versioned path (e.g. <...>/ms-playwright/firefox-1509/firefox/firefox.exe) but the binary itself isn't downloaded until the install step. An agent that probes executable_path to "verify Firefox is set up" gets a false positive, then crashes inside the first heredoc with BrowserType.launch: Executable doesn't exist at <path>. The Playwright error message is clear, but it costs a heredoc round-trip and is avoidable.

Changes

Single file: skills/webwright/SKILL.md — Prerequisites section only.

1. Switch the install command to python -m playwright install firefox. Official-equivalent invocation, resolves uniformly across Windows / macOS / Linux / virtualenvs / Windows Store Python.

2. Add a one-line preflight check the agent can run before the first heredoc:

   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')"

   Prints FIREFOX_READY / NEEDS_INSTALL. Cheap (a few hundred ms), gives the agent a deterministic detect-and-install branch instead of relying on the first heredoc to surface the error.

3. Short narrative around both, explaining why executable_path existing on disk is the right check (not just "playwright is installed").

No changes to any heredoc patterns. No new dependencies. No behavior change for users who already have Firefox installed.

Verification

On the same Windows 11 + Python 3.12 (Windows Store) machine where I originally hit the command not found failure:

$ python -m playwright install firefox
Downloading Firefox 146.0.1 (playwright firefox v1509) ... 100% of 110.2 MiB
Firefox 146.0.1 (playwright firefox v1509) downloaded to C:\Users\...\ms-playwright\firefox-1509

$ 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')"
FIREFOX_READY

Confirmed NEEDS_INSTALL is printed when the versioned firefox dir exists but the binary inside it does not (e.g. after a pip install -U playwright that bumps the bundled Firefox revision but doesn't re-download).

Test plan

• Confirmed playwright install firefox (bare) fails with command not found on stock Windows 11 + Python 3.12 (Windows Store).
• Confirmed python -m playwright install firefox succeeds on the same machine.
• Confirmed the preflight one-liner returns FIREFOX_READY after install and NEEDS_INSTALL when the binary is absent.
• Ran a full Webwright arxiv-search task end-to-end after the install — Firefox launches cleanly, all critical points verified.

Related

Independent of #8 (which fixes a UnicodeEncodeError in playwright_patterns.md heredocs on Windows). Same overall onboarding flow on Windows but a different file and different root cause — kept atomic so reviews don't have to weigh them together.