jmagly Browser Doctor Skill (DRAFT)
Status: DRAFT — scaffolded from PoC. Implementation pending Inception outputs.
Purpose
Diagnostic, read-only health check. Tells the user what's wired correctly and what needs browser-setup or browser-reset to fix.
When This Skill Applies
- After
browser-setupto verify the wizard's work - Before debugging "why isn't the agent driving my browser?"
- In CI / smoke tests to detect drift (extension uninstalled, token rotated, provider config rewritten)
Checks (planned)
| # | Check | Pass criteria | On fail |
|---|---|---|---|
| 1 | Browser binary present | Configured browser path exists and is executable | aiwg run skill browser-setup to re-detect |
| 2 | Browser version | <binary> --version returns a known-good version |
Update browser or document version mismatch |
| 3 | Extension installed | <profile>/Extensions/mmlmfjhmonkocbjadbfplnigmagldckm/ exists |
Install from Web Store; rerun setup |
| 4 | Token file present | ~/.config/playwright-mcp/token exists |
aiwg run skill browser-reset |
| 5 | Token file mode | mode 600, owner-only | chmod 600 ~/.config/playwright-mcp/token |
| 6 | Token file non-empty | size > 16 bytes | Re-capture token via reset |
| 7 | AIWG MCP registered | aiwg mcp list includes playwright |
browser-setup |
| 8 | MCP args correct | Args include --extension |
Re-register with correct args |
| 9 | MCP env block | PLAYWRIGHT_MCP_EXTENSION_TOKEN in env |
Re-register with env block |
| 10 | Provider injected | Active provider config contains playwright in mcpServers |
aiwg mcp inject --provider <p> --servers playwright |
| 11 | Provider env passthrough | Provider config's playwright entry preserves env | Re-inject |
| 12 | Probe connect | Spawn MCP, list tools, find browser_tabs |
See diagnostics; likely token mismatch |
| 13 | Allow-list present (optional) | .aiwg/browser-allowlist.yaml exists |
cp templates/browser-allowlist.yaml.tmpl .aiwg/browser-allowlist.yaml |
| 14 | Conflicting overrides | No --mcp-config wrapper detected for the active provider |
Document precedence; remove wrapper or add playwright to it |
Output
Structured JSON suitable for both human display and CI consumption:
{
"summary": { "passed": 13, "failed": 1, "skipped": 0 },
"checks": [
{
"id": 1,
"name": "Browser binary present",
"status": "pass",
"detail": "/usr/bin/google-chrome (148.0.7778.167)"
},
{
"id": 13,
"name": "Allow-list present (optional)",
"status": "warn",
"detail": ".aiwg/browser-allowlist.yaml not found",
"remediation": "cp $AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/templates/browser-allowlist.yaml.tmpl .aiwg/browser-allowlist.yaml"
}
]
}
Plain-text rendering for interactive use:
Browser Control — Health Check
==============================
[PASS] 1/14 Browser binary present /usr/bin/google-chrome (148.0.7778.167)
[PASS] 2/14 Browser version recent enough
[PASS] 3/14 Extension installed mmlmfjhmonkocbjadbfplnigmagldckm
[PASS] 4/14 Token file present ~/.config/playwright-mcp/token
…
[WARN] 13/14 Allow-list (optional) not scaffolded; consider adding
13 PASS, 1 WARN, 0 FAIL
Constraints
- Read-only — never writes, never modifies registry or configs
- Never echoes token value (only checks existence + mode + length)
- Probe check spawns + kills within a few seconds; no persistent side effects
Open implementation questions
- Should "probe connect" be opt-in (
--probe) since it spawns a process? - Should we cache last-known-good versions per browser to detect downgrades?
- How aggressively to flag #14 (conflicting overrides)? In some workspaces (e.g., this one with
claude-role), the override is intentional.
References
.aiwg/architecture/adr-remote-browser-control.mdskills/browser-setup/SKILL.md(this addon)skills/browser-reset/SKILL.md(this addon)