# Surfwright

> Use SurfWright CLI for deterministic browser control. Prefer JSON, explicit handles, and typed error codes.

- Skill: `marcohefti/surfwright` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add marcohefti/surfwright`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcohefti/surfwright/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: marcohefti (https://skillmd.com/u/marcohefti)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/marcohefti/surfwright

---


# SurfWright Skill

Deterministic browser control with JSON-first outputs and explicit handles.

## Discovery (Two Lanes)

- Action first: run mission commands directly.
- Fast lane bootstrap: `surfwright contract --profile browser-core`.
- Do not probe with `which`, help flags, or repeated skill file reads.
- Use `surfwright contract --command <id>` only after a command-id miss.
- Use `surfwright contract --commands <id1,id2,...>` for small miss batches.
- Use `surfwright contract --full` only for deep-lane catalog discovery.

## Runtime Rules

- Keep default JSON output; do not parse prose.
- Confirm required JSON schema via `surfwright contract --command <id>` only after a command-id miss.
- Start headless unless explicitly instructed otherwise.
- For workspace extension workflows, verify `open`/`session` payload `appliedExtensions[*].state == runtime-installed` before proceeding.
- Treat non-zero exits as typed failures and branch on `code` (`retryable` when present).
- Use one unique `--agent-id` per task.
- Treat daemon queue overload codes (`E_DAEMON_QUEUE_TIMEOUT`, `E_DAEMON_QUEUE_SATURATED`) as backpressure.
- If daemon transport is unreachable and continuity matters, use `SURFWRIGHT_DAEMON=0`.
- For non-trivial plans, prefer `run --plan <file>` (or `--plan -`) over inline `--plan-json`.
- For complex JavaScript, prefer `target eval --script-file` / `--script-b64`.
- Prefer typed primitives over eval when possible: `target count`, `target attr`, `target click --nth`, `target click --count-after`.