web-browser

web-browser Skill

Original author unknown · Modified and maintained by Kaiyu (KAIYU) Version: v2.1.0

Cross-platform compatibility

Item	macOS / Linux	Windows
Environment check	`bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh`	Requires Git Bash or WSL to run
Temporary file path	`/tmp/shot.png`	`%TEMP%\shot.png`
Chrome user data	`~/Library/Application Support/Google/Chrome/`	`%LOCALAPPDATA%\Google\Chrome\User Data\`
Node.js installation	`brew install node`	`winget install OpenJS.NodeJS.LTS`

Note for Windows users: check-deps.sh is a bash script and needs to be run via Git Bash or WSL. For screenshot paths, please use %TEMP%\shot.png instead of /tmp/shot.png。

Pre-check

Before starting networking operations, first check CDP mode availability:

If the following script reports an error or is missing dependencies, read SETUP.md to complete the initial configuration.

bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh

Node.js 22+: Required (uses native WebSocket). Versions below 22 can be used but require installing the ws module.
Chrome remote-debugging: Open in the Chrome address bar chrome://inspect/#remote-debugging, check "Allow remote debugging for this browser instance" and it is done; the browser may need to be restarted.

After the check passes, start the CDP Proxy to perform operations; if it does not pass, guide the user to complete the setup.

Browsing philosophy

Think like a human, completing tasks with both efficiency and adaptability.

When executing tasks, do not over-rely on steps planned from fixed impressions; instead, enter with a goal, judge as you look, solve obstacles when encountered, and go deeper when content is found to be insufficient—making decisions throughout around "what am I trying to achieve." All behavior of this skill should follow this logic.

① Get the request — First clarify what the user wants to do and define the success criteria: what counts as done? What information needs to be obtained, what operations need to be performed, what result needs to be achieved? This is the anchor for all subsequent judgments.

② Choose the starting point — Based on the nature of the task, platform characteristics, and achievement conditions, choose the approach most likely to get there directly as the first step to verify. Succeeding on the first try is of course best; if not, adjust in ③. For example, if you need to operate a page, need a logged-in state, or the platform is known to be unreachable via static methods (Xiaohongshu, WeChat Official Accounts, etc.) → go directly to CDP

③ Process verification — The result of each step is evidence, not just a binary signal of success or failure. Use the result against the success criteria in ① to update your judgment of the goal: is the path progressing? Does the overall shape of the result (quality, relevance, magnitude) indicate the goal is reachable? If you find the direction is wrong, adjust immediately; do not repeatedly retry the same method—a search with no hits does not mean "the right method has not been found yet," it may also mean "the target does not exist"; an API error, a page missing expected elements, or retries with no improvement are all telling you to re-evaluate the direction. When encountering obstacles such as pop-ups or login walls, judge whether they really block the goal: if they do, handle them; if not, bypass them—the content may already be in the page DOM, and the interaction is only a display mechanism.

④ Completion judgment — Against the defined task success criteria, stop only after confirming the task is complete, but do not over-operate either, and do not waste cost for the sake of "completeness."

Networking tool selection

Ensure the authenticity of information; first-hand information is better than second-hand informationSearch engines and aggregation platforms are information discovery entry points. When multiple search attempts yield no qualitative improvement, escalate to more fundamental acquisition methods: locate primary sources (official websites, official platforms, original pages).

Scenario	Tool
Search summaries or keyword results, discover information sources	WebSearch
URL is known, need to extract specific information from a page in a targeted way	WebFetch(fetch web page content, extracted by a small model according to a prompt, return the processed result)
URL is known, need the raw HTML source (meta, JSON-LD and other structured fields)	curl
Non-public content, or platforms known to be ineffective at the static layer (public content on Xiaohongshu, WeChat Official Accounts, etc. is also restricted by anti-scraping)	Browser CDP(direct, skip the static layer)
Need a logged-in state, interactive operations, or need to freely navigate and explore within the browser like a human	Browser CDP

Browser CDP does not require the URL to be known—you can start from any entry point and find the target content through in-page search, clicking, navigation, etc. WebSearch, WebFetch, and curl all do not handle logged-in states.

Jina(optional preprocessing layer, can be used in combination with WebFetch/curl; due to its characteristics it can save token consumption, so actively use it in combination when suitable for the task): a third-party web service that can convert web pages to Markdown, greatly saving tokens but possibly causing information loss. The invocation method is r.jina.ai/example.com(prefix added before the URL, without preserving the original URL's http prefix), limited to 20 RPM. Suitable for article-, blog-, documentation-, PDF- and other body-text-centric pages; for non-article-structure pages such as data dashboards and product pages, it may extract the wrong blocks.

After entering the browser layer,/eval are your eyes and hands:

See: use /eval to query the DOM and discover links, buttons, forms, and text content on the page—equivalent to "see what this page has"
Do: use /click to click elements,/scroll to scroll and load,/eval to fill out and submit forms—navigate naturally within the page like a human
Read: use /eval to extract text content, and determine whether images/videos carry core information—if so, extract the media URL for targeted reading or /screenshot visual recognition

When browsing within a page,first eval to understand the page structure, then decide the next action—when you see a list, click into the details; when you see pagination, turn the page; when you see content, extract it. There is no need to plan all the steps in advance.

Programmatic operations and GUI interaction

There are two ways to operate a page within the browser:

Programmatic approach(constructing URLs for direct navigation, eval to manipulate the DOM): when successful, it is fast and precise, but to the website it is not normal user behavior and is more likely to trigger anti-scraping mechanisms.
GUI interaction(clicking buttons, filling in input boxes, scrolling and browsing): GUI is designed for humans, and websites will not restrict normal UI operations; it has the highest certainty, but involves many steps and is slow.

Judge based on your understanding of the target platform. When the programmatic approach is blocked, GUI interaction is a reliable fallback. Note: do not construct URLs with parameters from memory—internal parameters (city codes, category IDs, etc.) can change at any time; when uncertain, obtain the actual links through page interaction or by extracting them from the DOM.

Browser CDP Mode

Connect directly to the user's everyday Chrome via CDP Proxy, naturally carrying the login state, with no need to launch a separate browser. Unless the user explicitly requests it, do not proactively operate the user's existing tabs. Perform all operations in background tabs that you create yourself, keeping intrusion into the user's environment to a minimum. On the premise of not closing the user's tabs, close the tabs you created after completing the task, keeping the environment tidy.

Startup

bash ${CLAUDE_SKILL_DIR}/scripts/check-deps.sh

The script checks Node.js and the Chrome port in sequence, and ensures the Proxy is connected (if not running, it starts automatically and waits). After starting, the Proxy keeps running.

Proxy API

All operations call the HTTP API via curl:

# 列出用户已打开的 tab
curl -s http://localhost:3456/targets

# 创建新后台 tab（自动等待加载）
curl -s "http://localhost:3456/new?url=https://example.com"

# 页面信息
curl -s "http://localhost:3456/info?target=ID"

# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'

# 捕获页面渲染状态（含视频当前帧）
# macOS/Linux: /tmp/shot.png | Windows: %TEMP%\shot.png
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"

# 导航、后退
curl -s "http://localhost:3456/navigate?target=ID&url=URL"
curl -s "http://localhost:3456/back?target=ID"

# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'

# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'

# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'

# 滚动（触发懒加载）
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"

# 关闭 tab
curl -s "http://localhost:3456/close?target=ID"

In-page navigation

Two ways to open links within a page:

/click: Click directly within the current tab. Simple and direct, processed serially. Suitable for scenarios requiring continuous operations within the same page, such as clicking to expand, pagination, entering details, etc.
/new + full URL: Extract the full address of an object link from the DOM (including all query parameters) and open it in a new tab. Suitable for scenarios requiring simultaneous access to multiple pages.

Many websites' links contain session-related parameters (such as tokens), which are necessary for normal access. When extracting URLs, keep the full address; do not trim or omit parameters.

Media Resource Extraction

When determining that content is inside an image, use /eval to get the image URL directly from the DOM, then read it in a targeted way—far more precise than a full-page screenshot.

Technical Facts

A page contains a large amount of content that has been loaded but not displayed—images in carousels that are not the current frame, text in collapsed sections, lazy-load placeholder elements, etc. They exist in the DOM but are invisible to the user. Thinking in units of data structures (containers, attributes, node relationships), these contents can be reached directly.
/scroll Scrolling to the bottom triggers lazy loading, causing images that have not entered the viewport to finish loading. If you do not scroll before extracting image URLs, some images may not yet be loaded.
After obtaining the media resource URL, public resources can be downloaded locally and then read; only resources that require a login state to obtain need navigate + screenshot in the browser.
Intensively opening a large number of pages in a short time (such as batch /new) may trigger the website's anti-scraping risk control.

Video Content Acquisition

The user's Chrome renders for real, and screenshots can capture the current video frame. Core capability: through /eval control the <video> element (get duration, seek to any time point, play/pause/fullscreen), combined with /screenshot frame sampling, discrete sampling analysis of video content can be performed.

Login Determination

The user's everyday Chrome naturally carries the login state, and most commonly used websites are already logged in.

There is only one core question in login determination:Has the target content been obtained?

After opening the page, first try to obtain the target content. Only when it is confirmed thatthe target content cannot be obtainedand it is determined that logging in would solve it, inform the user:

"The current page cannot obtain [specific content] in a logged-out state. Please log in to [website name] in your Chrome, and tell me to continue when done."

After logging in, there is no need to restart anything; just refresh the page and continue.

Task End

Use /close to close the tabs you created; the user's original tabs must be preserved and unaffected.

The Proxy runs continuously; proactively stopping it is not recommended—after a restart, the CDP connection needs to be re-authorized in Chrome.

Parallel research: sub-agent divide-and-conquer strategy

When a task contains multipleindependentresearch objectives (such as researching N projects or N sources simultaneously), reasonably dividing the work among sub-agents for parallel execution is encouraged, rather than having the main agent handle them serially.

Benefits:

Speed: with multiple sub-agents running in parallel, total elapsed time is roughly equal to the duration of a single subtask
Context protection: scraped content does not enter the main agent's context; the main agent receives only summaries, saving tokens

Parallel CDP operations: each sub-agent, within the current user browser instance, creates the background tabs it needs (/new), operates them itself, and closes them itself when the task ends (/close). All sub-agents share one Chrome and one Proxy, operating different tabs via different targetIds, with no race-condition risk.

How to write sub-agent prompts: goal-oriented, not step instructions

You must write 必须加载 web-browser skill 并遵循指引 in the sub-agent prompt; the sub-agent will automatically load the skill, so there is no need to copy the skill content or specify paths in the prompt.
Sub-agents have autonomous judgment. The main agent's responsibility is to clearly statewhat is wanted, and to constrainhow to do itonly when necessary and certain. Over-specifying steps deprives the sub-agent of its judgment space and instead introduces the main agent's mistaken assumptions.Avoid wording in the prompt that hints at the sub-agent's behavior: "search for xx" anchors the sub-agent to WebSearch, whereas in fact some anti-scraping sites require CDP to directly access the main site in order to effectively obtain content. When writing prompts, the main agent should describe the goal ("obtain", "research", "learn about") and avoid verbs that hint at specific means ("search", "scrape", "crawl").

Criteria for divide-and-conquer:

Suitable for divide-and-conquer	Not suitable for divide-and-conquer
Goals are mutually independent, and results do not depend on each other	Goals have dependencies, where the next one needs the previous one's result
Each subtask is large enough (multi-page scraping, multiple rounds of search)	Simple single-page queries, where divide-and-conquer overhead exceeds the benefit
Tasks that require a CDP browser or long-running execution	Lightweight queries that a few WebSearch / Jina calls can complete

Information verification tasks

The target of verification isprimary sources, not more secondhand reports. Multiple media outlets citing the same error can create an illusion of circular confirmation.

Search engines and aggregation platforms are entry points for information discovery and are tools forlocatinginformation; they cannot be used to directlyproveauthenticity. After finding a source, access and read the original text directly. The same principle applies to research on tool capabilities/usage—official documentation is a primary source; when uncertain, check the documentation or source code first rather than guessing.

Information type	Primary source
Policies/regulations	Official website of the issuing agency
Corporate announcements	Company official news page
Academic statements	Original papers/institutional official websites
Tool capabilities/usage	Official documentation, source code

When the official website cannot be found: Original reporting by authoritative media (not reprints) may serve as a secondary basis, but the user must be informed: "No official original text was found; the following verification comes from a [media name] report and may contain transcription errors." When there is a single source, likewise declare this to the user.

Site experience

Experience with specific websites accumulated during operations, stored by domain under references/site-patterns/ .

Sites with existing experience:!ls ${CLAUDE_SKILL_DIR}/references/site-patterns/ 2>/dev/null | sed 's/\.md$//' || echo "暂无"

After determining the target website, if there is a matching site in the list above, the corresponding file must be read to obtain prior knowledge (platform characteristics, effective patterns, known pitfalls). Experience content is marked with the discovery date and should be treated as a possibly valid hint rather than a guarantee—if operations based on the experience fail, fall back to the general pattern and update the experience file.

After a CDP operation completes successfully, if a new site or new pattern worth recording experience about is discovered (URL structure, platform characteristics, operation strategy), proactively write it to the corresponding site experience file. Write only verified facts, not unconfirmed guesses.

File format:

---
domain: example.com
aliases: [示例, Example]
updated: 2026-03-19
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实

## 有效模式
已验证的 URL 模式、操作策略、选择器

## 已知陷阱
什么会失败以及为什么

Experience/pitfall content is marked with the discovery date and should be treated as a "possibly valid hint" rather than a "guaranteed correct fact."

References index

File	When to load
`references/cdp-api.md`	When detailed CDP API reference, JS extraction patterns, or error handling is needed
`references/site-patterns/{domain}.md`	After determining the target website, read the corresponding site experience