playwright-mcp-skill

name	playwright-mcp-skill
description	Run browser automation through @playwright/mcp over UXC stdio MCP, with daemon-friendly session reuse and safe action guardrails. Use when tasks need deterministic page navigation, DOM snapshots, and scripted browser interaction from CLI.

Playwright MCP Skill

Use this skill to run Playwright MCP operations through uxc using fixed stdio endpoints.

Reuse the uxc skill for generic protocol discovery, auth/error handling, and envelope parsing rules.

Prerequisites

• uxc is installed and available in PATH.
• npx is available in PATH (Node.js installed).
• Network access for first-time @playwright/mcp package fetch.
• Browser runtime can start locally (headless mode is default in this skill).

Core Workflow (Playwright-Specific)

Endpoint candidate inputs before finalizing:

• Raw package form from docs: npx @playwright/mcp@latest
• Reliable non-interactive form: npx -y @playwright/mcp@latest
• Isolated/headless stable form (default for this skill):
  • npx -y @playwright/mcp@latest --headless --isolated
  • Shared-profile headless form (for persistent login state):
  • npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile
  • Shared-profile headed form (for interactive debug with same login state):
  • npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile

1. Verify protocol/path from official source and probe:
   • Official source: https://github.com/microsoft/playwright-mcp
   • probe candidate endpoints with:
     • uxc "npx -y @playwright/mcp@latest --headless --isolated" -h
   • Confirm protocol is MCP stdio (protocol == "mcp" in envelope).
2. Detect auth requirement explicitly:
   • Run host help or a minimal read call and inspect envelope.
   • @playwright/mcp default flow is no OAuth/API key for local stdio use.
3. Use fixed link command by default:
   • command -v playwright-mcp-cli
   • If missing, create it:
     • uxc link playwright-mcp-cli "npx -y @playwright/mcp@latest --headless --isolated"
   • Optional shared-profile dual command setup for persistent sessions:
     • command -v playwright-mcp-headless
     • command -v playwright-mcp-ui
     • uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-headless "npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile"
     • uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-ui "npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile"
   • playwright-mcp-cli -h
   • If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.
4. Inspect operation schema before execution:
   • playwright-mcp-cli browser_navigate -h
   • playwright-mcp-cli browser_snapshot -h
   • playwright-mcp-cli browser_click -h
5. Prefer read-first interaction:
   • Start with navigation/snapshot before mutating page state.
6. Execute actions with explicit confirmation when impact is high:
   • Confirm before form submission, checkout, delete/destructive actions, or irreversible multi-step flows.

Guardrails

• Keep automation on JSON output envelope; do not rely on --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Use playwright-mcp-cli as default command path.
• playwright-mcp-cli <operation> ... is equivalent to uxc "npx -y @playwright/mcp@latest --headless --isolated" <operation> ....
• Use direct uxc "<endpoint>" ... only as temporary fallback when link setup is unavailable.
• If browser profile conflict appears, keep --isolated in endpoint and retry via the same fixed link command.
• When using shared --user-data-dir, run headless/headed links serially (not concurrently).
• To enable seamless switching between headed UI login and headless CLI automation using the same profile directory, set a daemon exclusive key:
  • Prefer link-level setup (recommended above), or set UXC_DAEMON_EXCLUSIVE=~/.uxc/playwright-profile for ad-hoc runs.
  • If the profile is still busy (another session is actively running), fallback: uxc daemon stop
• Prefer browser_snapshot over screenshots for model-action loops.

References

• Invocation patterns:
  • references/usage-patterns.md