| 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. |
