claude-tweaks-browse

name	claude-tweaks:browse
description	Use for browser automation via agent-browser — defines session naming, screenshot/trace paths, and operation vocabulary used by /stories, /visual-review, /review, and /demo. Keywords - browse, browser, agent-browser, screenshot, scrape, automation.

Interaction style: Present single decisions via the AskUserQuestion tool (options with one marked Recommended) instead of a plain-text numbered list. For multi-item decisions, render a batch table with recommended actions pre-filled, then capture the apply-all/override decision via one AskUserQuestion call. Never make more than one AskUserQuestion call per logical decision — resolve each before showing the next. End skills with a ## Next Actions block rendered via AskUserQuestion (context-specific options, one recommended), not a navigation menu.

Browse — Browser Conventions

Conventions skill for browser automation. Defines session naming, screenshot/trace paths, lifecycle, and the abstract operation vocabulary that /claude-tweaks:stories, /claude-tweaks:visual-review, /claude-tweaks:review, /claude-tweaks:demo, and the qa-agent all speak. Concrete agent-browser syntax lives in agent-browser-reference.md in this skill's directory.

                             [ /claude-tweaks:browse ] ← utility (no fixed lifecycle position)
                                        ↑
   Used by: /claude-tweaks:stories, /claude-tweaks:visual-review,
            /claude-tweaks:review (visual + qa modes), /claude-tweaks:demo
            (on-demand live look), qa-agent, ad-hoc tasks

When to Use

• /claude-tweaks:stories is exploring a site or validating generated stories against the live DOM
• /claude-tweaks:visual-review is walking pages or journeys for UI quality findings
• /claude-tweaks:review is running its visual or QA modes
• /claude-tweaks:demo opens an on-demand live look at a record's resolved entry point ("Show me live")
• A consumer skill needs to dispatch parallel agents that each drive a browser
• Ad-hoc browser ops — navigate, screenshot, scrape, fill a form, check a deployment

Requirements

agent-browser must be installed. See _shared/browser-detection.md for the detect / install / verify procedure, daemon lifecycle (auto-starts on port 4848), and recovery (agent-browser doctor).

Input

$ARGUMENTS is freeform — a URL, a task description, or a session-management command. There is no fixed argument schema; the skill translates the request into one or more agent-browser operations.

Pattern	Example	Behavior
(none)	—	Show session conventions and exit, or list active sessions
<URL>	https://example.com	Open a default session at the URL and snapshot
<task description>	walk the checkout flow on https://example.com	Plan and execute multi-step ops to satisfy the task
--session <name> open <URL>	--session checkout-flow open https://example.com	Open a named session
--session <name> click "<selector>"	--session checkout-flow click "button[name='Pay']"	Operate within a named session
set viewport <wxh>	set viewport 1280x800	Adjust viewport for the active session
set device "<name>"	set device "iPhone 14"	Emulate a device profile
backend=chrome <URL or task>	backend=chrome https://app.example.com/settings	Routes through the native mcp__claude-in-chrome__* tools (user's live authenticated Chrome session) instead of agent-browser. Human-invoked only.

See agent-browser-reference.md in this skill's directory for the full operation vocabulary (snapshot, find, fill, type, vitals, trace, batch, react, auth vault, viewport/device flags).

backend=chrome is a narrow escape hatch, not a second backend: it covers navigate, read page, click, type/fill, and screenshot only — no vitals, trace, react introspection, or auth vault (the session is already authenticated, so the vault has no job). It is never auto-selected and must never be used by /stories, /visual-review, /review, qa-agent, /flow, or a Routine — those stay agent-browser-only, per CLAUDE.md's Don'ts.

Conventions Defined Here

These are the contract every browser-touching skill follows.

Session naming

Kebab-case, derived from purpose. One session per parallel agent, one per QA story instance. Session names are visible in the dashboard and in trace paths, so make them descriptive.

Examples: checkout-flow, signup-neg-1, pricing-page-review, qa-cart-empty-state.

Screenshot path

screenshots/browse/<session>/<NN>_<description>.png

<NN> is a zero-padded sequence number; <description> is a short kebab-case label. Example: screenshots/browse/checkout-flow/02_payment-error.png.

Minimum two screenshots per task: one after initial load, one at the final state. Annotated screenshots (numbered overlays matching snapshot refs) follow the same path convention.

Trace path

traces/<session>/<timestamp>.zip

Capture a trace before closing a session whenever a step fails. Failure reports must include the trace path. There is no automatic retention policy — users manage cleanup.

Lifecycle

open  →  ops (snapshot, find, click, fill, screenshot, vitals, …)  →  close

Daemon is implicit. Always close the session when the task is done — leaked sessions consume resources. On step failure: capture trace, then close. List sessions with agent-browser session list if you suspect leaks.

Operation vocabulary

Consumer skills speak abstract operation names (open, snapshot, find, click, fill, type, screenshot, vitals, trace, close, …). The translation to concrete agent-browser commands lives in agent-browser-reference.md in this skill's directory. Read that file before invoking commands you do not have memorized.

Operation Mapping

Condensed pointer table. Full reference (batch, react, auth vault, vitals, trace, viewport/device flags) lives in agent-browser-reference.md.

Operation	Command
open	agent-browser --session <name> open <url>
snapshot (interactive, compact)	agent-browser --session <name> snapshot -i -c
find by role + name	agent-browser --session <name> find role <role> --name <name>
find by testid	agent-browser --session <name> find testid <id>
click	agent-browser --session <name> click <ref>
fill	agent-browser --session <name> fill <ref> <value>
type	agent-browser --session <name> type <ref> <text>
screenshot	agent-browser --session <name> screenshot --filename <path>
annotated screenshot	agent-browser --session <name> screenshot --annotate --filename <path>
vitals	agent-browser --session <name> vitals
trace save	agent-browser --session <name> trace save traces/<session>/<timestamp>.zip
close	agent-browser --session <name> close

Parallel Sessions

Each parallel agent gets its own --session <unique-name>. One browser instance per session. Memory cost scales with the number of concurrent sessions, not with the number of commands sent to a session — so reuse a session for sequential ops on the same page, and spin up a fresh session per parallel agent or per QA story instance.

Parallel execution: Dispatch independent browser walks as parallel Task agents — each opens its own session, runs its ops, and returns a per-session result. Assemble results after all agents complete.

Contract: Each agent follows _shared/subagent-output-contract.md — minimal input, status line first, output template inlined verbatim. Model tier: Standard.

Model tier: Standard (Sonnet) — browser-walk agents do multi-step navigation and structured observation, which exceeds Fast-tier mechanical extraction. Upgrade to Capable (Opus) only if the walk requires synthesis of subjective UX judgment.

Output template (each agent must follow exactly):

Use Template A when the walk reports issues / findings:

OUTPUT FORMAT (required):
Return ONLY a markdown table, no preamble:

| Severity | Path:Line | Finding | Evidence |
|---|---|---|---|
| critical | src/auth.ts:42 | Missing token expiry check | uses `<` not `<=` |
| medium | src/api.ts:180 | Unhandled rejection | line 184: `await fetch(...)` no try/catch |

Severity scale: critical / high / medium / low / info
If no findings: return literal text "No findings."
Do not add narration, headers, or summaries before or after the table.

Use Template B when the walk reports navigation locations / references:

OUTPUT FORMAT (required):
Return ONLY bullet lines, one per match:

- {path}:{line} — {one-line context}

If no matches: return literal text "No matches."
Do not add narration or grouping headers.

Each agent's first reply line must be one of DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED, then the chosen template.

Next Actions

Call AskUserQuestion:

• question: "What's next?", header: "Next step", multiSelect: false
• Option 1 — label: "Visual review (Recommended)", description: "/claude-tweaks:visual-review {url} — run a structured visual review against the page or journey just driven"
• Option 2 — label: "Generate stories", description: "/claude-tweaks:stories — generate or refresh QA story YAML files from the live DOM"
• Option 3 — label: "Full review", description: "/claude-tweaks:review {spec} full — full review pipeline including code, visual, and QA passes"
• Option 4 — label: "Capture idea", description: "/claude-tweaks:capture \"{idea}\" — save an idea surfaced while exploring the browser"

Component-Skill Contract

/claude-tweaks:browse is a conventions skill — it documents the operation vocabulary for agent-browser and is consumed transitively by /claude-tweaks:stories, /claude-tweaks:visual-review, /claude-tweaks:review, /claude-tweaks:demo, and the registered qa-agent. Those callers either inline the relevant operation text directly in their own dispatch prompts (parallel-session pattern) or call agent-browser commands by name; they do not "invoke" /browse as a workflow step. As a result, the ## Next Actions block renders only when a user invokes /browse directly — when a parent skill is using these conventions as a knowledge dependency, no parent handoff exists to defer to and no Next Actions render in the parent's context. Detection: there is no PIPELINE_RUN_DIR signal because /browse never runs as a pipeline stage.

Anti-Patterns

Pattern	Why It Fails
Polling the dashboard programmatically	http://localhost:4848 is a human debug surface — scraping it is brittle and unsupported
Storing @eN snapshot refs in YAML or persisted artifacts	Refs are session-scoped and regenerate on every snapshot — resolve them at runtime via find
Batching across sessions	One agent-browser batch invocation owns a single session's lifecycle — never mix session names in one batch
Using CSS or XPath selectors with find	Schema v2 forbids CSS/XPath — use semantic locators only (role, name, text, testid, label, placeholder)
Generic session names (test, session1)	Names show up in dashboards and trace paths — derive from purpose
Forgetting to close sessions	Leaked sessions consume memory — always close at the end of a run
Skipping the trace on failure	Failure reports without a trace path are not actionable — capture before closing
A consumer skill routes through backend=chrome	Breaks portability to hosted Routines — agent-browser is the only backend that works headless; this flag is human-invoked only

Relationship to Other Skills

Skill	Relationship
/claude-tweaks:stories	Consumes /browse conventions for session naming, screenshot paths, and the operation vocabulary used to resolve semantic locators at runtime
/claude-tweaks:visual-review	Drives page, journey, and discover walks against /browse's lifecycle; uses annotated screenshots and vitals from the operation table. /visual-review is the review procedure; /browse is the conventions reference for session naming, screenshot paths, trace paths, and the operation vocabulary.
/claude-tweaks:review	Delegates to /visual-review (visual mode) and qa-agent (QA mode) — both speak /browse's operation vocabulary transitively
qa-agent (agents/qa-agent.md)	Each story instance opens a uniquely named session; uses the auth vault and trace-on-failure conventions defined here
/claude-tweaks:test	Invokes qa-agent for QA story validation; trace paths from failed stories surface in /test reports
/claude-tweaks:init	Detects agent-browser availability during setup and records the requirement that /browse depends on
/claude-tweaks:research	Both utility skills (no fixed lifecycle position). /browse is interactive browser automation; /research is autonomous multi-source web research.
/claude-tweaks:flow	/flow invokes /review in full mode by default, which transitively drives /visual-review and /browse for the browser portion. Browser availability detected at /flow startup determines whether visual review runs.
/claude-tweaks:help	/help lists /browse in the utility skills table and surfaces availability when scanning for browser-dependent recommendations.
/claude-tweaks:demo	/demo's "Show me live" option (Step 3) opens an on-demand agent-browser session at a record's resolved entry point, following /browse's session-naming and lifecycle conventions directly — not a workflow-step invocation, the same relationship /visual-review has with /browse.