Skill: surfagentapp/surfagent-browser-operations (version 1.1.0)

--- name: browser-operations description: Core browser operations skill for SurfAgent and similar browser agents, covering tab discipline, perception-first execution, human-like driving, proof rules, and token-efficient fallback patterns. version: 1.1.0 metadata: openclaw: homepage: https://surfagent.app emoji: "🧭" --- # Browser Operations > The core skill. Use this before any site-specific skill. This file teaches the universal rules for driving a real browser without making a mess, wasting tokens, or lying about success. ## 1. What this skill is for Use this skill for: - browser hygiene - tab hygiene - perception-first workflow - autonomy loops - human-like interaction patterns - token-efficiency rules - generic fallback and recovery patterns - proof rules Use a platform skill after this one when you are on a known site like Gmail, X, Discord, or GitHub. ## 2. Non-negotiables 1. One active work tab per target site unless a second tab is clearly justified. 2. Reuse a healthy tab before opening a new one. 3. Perceive state before acting. 4. Verify visible results after acting. 5. Prefer low-token state and perception tools over giant raw reads. 6. Do not claim success from an attempted click or type alone. 7. If retries create tab sprawl, stop and clean up before continuing. ## 3. Tool selection ladder Default order: 1. perception or state layer first 2. platform adapter second 3. MCP server when available and stronger for the job 4. raw browser actions only as fallback Interpretation: - Start with the cheapest reliable understanding layer. - Use site-specific abstractions when they reduce error rate or token burn. - Fall back to raw browser control only when the higher-level tools are missing or insufficient. ## 4. Browser hygiene Before work: - inspect open tabs - choose the tab you will operate - confirm URL, title, and whether it is already logged in During work: - keep a clear tab budget - avoid duplicate retries on the same site - if a tab becomes stale or broken, hand off to one fresh tab and close the stale one After work: - close throwaway tabs - leave the browser in a clean, explainable state ## 5. Tab hygiene Healthy pattern: - one site, one active tab - one deliberate exception if comparison, auth handoff, or reference context is required Unhealthy pattern: - multiple duplicate tabs from retries - stale tabs left open after handoff - guessing which tab is live instead of checking If tab state is unclear, stop and re-enumerate before acting. ## 6. Perception-first loop Use this loop by default: 1. perceive or inspect state 2. choose the next action 3. act once 4. diff or verify what changed 5. repeat only if the page state supports the next step Ask after every action: - what changed? - did the intended element update? - did a blocker appear? - is the page now in a different mode? If the surface is visually dense, stateful, or contradictory, escalate to a screenshot or visual snapshot early. Examples where visual confirmation should happen fast: - account switchers - modals and drawers - multi-mode composers - community or group posting surfaces - pages where DOM extraction and visible state disagree Rule: do not keep arguing with partial extraction when one screenshot can settle the page state. ## 7. Autonomy layer The autonomy layer should be small and disciplined. Use short plan-act-verify cycles: - identify the immediate goal - take one concrete action - verify the result - update the local plan from evidence, not hope Do not queue five blind actions in a row on a dynamic site. ## 8. Human-like driving Drive like a careful operator, not a broken macro: - prefer deliberate clicks over frantic retries - wait for visible state changes, not arbitrary long sleeps - scroll only when needed - type into the intended field once it is confirmed focused or targeted - avoid racing modals, redirects, or page transitions Human-like does not mean fake random noise. It means paced, state-aware interaction. ## 9. Token-efficiency rules Always prefer: - structured state over full DOM dumps - perception summaries over giant page reads - targeted evaluate calls over broad scraping - delta checks over repeated full snapshots - platform adapters and MCPs when they compress the task safely Avoid: - repeated giant browser reads - dumping full HTML when only one field matters - re-reading unchanged screens - broad selector fishing when the page can be classified first ## 10. Fallback ladder If the ideal path fails: 1. verify page state again 2. take a screenshot or visual snapshot if the surface is ambiguous 3. retry with a more precise selector or ref 4. switch to site adapter or MCP if available 5. recover page state, refocus, dismiss blocker, or reload 6. move to one fresh tab if the current one is poisoned 7. escalate to a platform skill or ask for human input only when the blocker is real ## 11. Common blockers Watch for: - cookie banners - consent modals - auth walls - captcha or verification gates - stale session pages - hidden compose or modal state - frozen or half-loaded tabs For each blocker: - name it plainly - confirm it is real - say whether it is auto-resolvable, retryable, or human-blocked ## 12. Proof rules Success requires visible evidence. Good proof usually includes: - correct page or modal is open - intended field values are present - intended action completed - resulting state is visible in UI - follow-up render or post-action state confirms success Examples: - sent email: compose populated, send confirmation shown, sent message renders correctly - login: auth state changed, destination page loaded, account identity visible - posted message: composer cleared or closed, new post visible in timeline or thread - saved setting: toggle/value changed and persists on reload or revisiting Bad proof: - click returned ok - selector existed - no error was thrown - assistant assumes the action worked ## 13. When to use platform skills Use a platform skill when the site has: - known brittle selectors - special editor behavior - auth or trust-safety edge cases - better adapters or MCP tools - site-specific proof requirements Priority first set: - Gmail - X/Twitter - Discord - GitHub ## 14. Minimal operating checklist Before claiming done, confirm: - right tab - right account - right page state - action executed - visible result verified - spare tabs cleaned up If a page was complex enough to confuse state during the run, add a short note to the platform skill or state map afterward so the next agent does not have to rediscover it. ## 15. Output contract for agents When reporting progress: - say what changed, not what you hoped would happen - call out blockers immediately - distinguish attempted from verified - keep the summary short and evidence-based ## 16. Relationship to other docs This is the universal browser brain. Pair it with: - platform skills for site-specific behavior - MCP or adapter docs for capability selection - runtime wrappers for Claude Code, Codex, Cursor, Hermes, and others


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)