amhuppert/my-ai-resources/browser-automation

Browser Automation with Playwright

Route the request to the right tool and let the dedicated skill drive the interaction. This file does not teach Playwright usage — it picks the tool, ensures the right skill is installed, and hands off.

Routing Decision

Pick one based on the use case:

Default to the CLI. Microsoft's own guidance: coding agents are better served by CLI + skills than by MCP. CLI saves snapshots to disk instead of streaming them into context (~4× fewer tokens per session) and avoids the ~3,400-token MCP tool-schema overhead on every message. See references/token-optimization.md for the full breakdown.

Use MCP only when no shell/filesystem is available, or for a one-shot interaction where setup overhead beats the per-action token savings.

Setup: Required Before Any CLI Workflow

The Playwright CLI ships its own Claude Code skill (playwright-cli) — the canonical, always-up-to-date command reference plus task playbooks (test running, request mocking, tracing, video recording, storage state, spec-driven testing, element-attribute inspection, session management). This skill never duplicates that content. It either defers to the official skill or installs it.

Step 1 — Detect

# Is the binary on PATH?
which playwright-cli || npx --no-install playwright-cli --version
 
# Is the skill installed (project-level or user-level)?
test -f .claude/skills/playwright-cli/SKILL.md && echo "project skill installed"
test -f ~/.claude/skills/playwright-cli/SKILL.md && echo "user skill installed"

Step 2 — Install if missing

Install without asking — Alex always wants the official skill present:

# Install the global binary if `which playwright-cli` failed
npm install -g @playwright/cli@latest
 
# Scaffold .playwright/ workspace, install default browser,
# and copy the skill to ./.claude/skills/playwright-cli/
playwright-cli install --skills

Briefly state what was installed (binary + skill path) so Alex can see it.

Step 3 — Hand off

After install, all CLI command reference and patterns come from the official `playwright-cli` skill. Do not invent commands, paraphrase its content here, or fall back to memory. Read its SKILL.md and the relevant references/*.md for the task at hand.

If you find yourself wanting to add CLI command examples to this skill, stop — the right place is upstream (the official skill) or, for our own router-level concerns, in references/token-optimization.md.

Architecture: Use Subagents for Browser Work

For sessions involving more than a few interactions, delegate to a subagent. The Playwright maintainer recommends this pattern explicitly: each subagent gets its own context loop, so browser snapshots and intermediate state accumulate there instead of in the main conversation.

"Use a subagent to: navigate to http://localhost:3000/settings,
 verify the theme toggle exists, click it, confirm dark mode applies.
 Report back pass/fail."

Self-Improvement

Watch for inefficiency or struggle:

• Repeated failed interactions (wrong refs, stale snapshots, elements not found)
• Excessive navigation when eval or direct URLs would suffice
• Tool mismatch (using MCP for a 30+ step session, or CLI for a single-step check inside an MCP-only client)
• Token waste (screenshots when snapshots suffice, redundant snapshots, full-page snapshots on huge apps)
• Missing knowledge in the official skill (auth flows, dynamic content, SPA edge cases, framework-specific quirks)

Surface concrete suggestions to Alex after the immediate task. For CLI command gaps, the fix is upstream in the official playwright-cli skill, not here. For routing, MCP, or token-economics gaps, propose specific edits to this skill or its references.

References

• `references/playwright-mcp-reference.md` — MCP setup, full tool catalog, configuration flags, and patterns. Use only when CLI isn't an option.
• `references/token-optimization.md` — Token cost analysis, per-tool optimization patterns, architecture-level decisions.