Pre-check
Before starting networked operations, first check CDP mode availability:
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
If it does not pass, guide the user to complete the setup:
- Node.js 22+: Required (uses native WebSocket). Versions below 22 are usable but require installing the
wsmodule. - 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, the following notice must be shown directly to the user in the reply, and then start the CDP Proxy to perform operations:
温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。
Browsing Philosophy
Think like a human, completing tasks with both efficiency and adaptability.
When executing tasks, do not overly 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 — make decisions throughout around "what do I want 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 complete? What information needs to be obtained, what operations need to be performed, and 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 conditions for completion, choose the approach most likely to reach the goal directly as the first step to verify. Success on the first try is naturally best; if not successful, adjust in ③. For example, if you need to operate the page, need a logged-in state, or know that a static approach cannot reach the platform (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 to compare against the success criteria in ① and update your judgment of the goal: is the path making progress? Does the overall appearance of the result (quality, relevance, scale) indicate that the goal is reachable? If you find the direction is wrong, adjust immediately; do not repeatedly retry the same method — a search not hitting does not mean "the right method has not been found yet"; it may also mean "the target does not exist"; API errors, missing expected page elements, and no improvement after retries are all telling you that it is time to reassess the direction. When encountering obstacles such as pop-ups or login walls, judge whether they truly block the goal: if they block it, handle them; if not, bypass them — the content may already be in the page DOM, and the interaction is only a presentation means.
④ Completion judgment — Compare against the defined task success criteria, and only stop after confirming the task is complete; but do not over-operate either, and do not waste cost for the sake of "completeness".
Networked Tool Selection
- Ensure the authenticity of information; first-hand information is better than second-hand information: Search engines and aggregation platforms are entry points for information discovery. When multiple search attempts yield no qualitative improvement, upgrade to a more fundamental acquisition method: locate first-hand sources (official websites, official platforms, original pages).
| Scenario | Tool |
|---|---|
| Search summaries or keyword results to discover information sources | WebSearch |
| The URL is known, and specific information needs to be extracted in a targeted way from the page | WebFetch(Fetch webpage content, extracted by a small model according to the prompt, returning the processed result) |
| URL is known, raw HTML source code (structured fields such as meta, JSON-LD, etc.) is needed | curl |
| Non-public content, or platforms whose known static layer is ineffective (public content on platforms such as Xiaohongshu and WeChat Official Accounts is also restricted by anti-scraping measures) | Browser CDP(direct, skip the static layer) |
| Requires login state, interactive operations, or the 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 do not handle login state.
Jina(Optional preprocessing layer, can be used in combination with WebFetch/curl; due to its characteristics it can save token consumption, so please actively use it in combination when suitable for the task): A third-party network service that converts 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, the original http prefix of the URL is not retained), limited to 20 RPM. Suitable for pages centered on main text such as articles, blogs, documents, PDFs, etc.; for non-article-structure pages such as data dashboards and product pages, it may extract incorrect blocks.
After entering the browser layer,/eval are your eyes and hands:
- See: use
/evalto query the DOM and discover links, buttons, forms, and text content on the page—equivalent to “take a look at what this page has” - Do: use
/clickto click elements,/scrollto scroll and load,/evalto fill in forms and submit—navigate naturally within the page like a human - Read: use
/evalto extract text content and determine whether images/videos carry core information—if so, extract the media URL to read in a targeted way or/screenshotvisual recognition
When browsing web pages,first understand the page structure, then decide the next action. There is no need to plan all steps in advance.
Programmatic operations and GUI interaction
There are two ways to operate pages within the browser:
- Programmatic approach(constructing URLs to navigate directly, using eval to manipulate the DOM): when successful, it is fast and precise, but to the website it is not normal user behavior and may trigger anti-scraping mechanisms.
- GUI interaction(clicking buttons, filling in input fields, scrolling and browsing): GUI is designed for humans, websites will not restrict normal UI operations, and it has the highest determinism, but it involves many steps and is slow.
Choose the method flexibly based on your understanding of the target platform. GUI interaction is also an effective probe for the programmatic approach—through one real interaction, observe the site's actual behavior (URL patterns, required parameters, page navigation logic) to provide a basis for subsequent programmatic operations; at the same time, when the programmatic approach is blocked, GUI interaction is a reliable fallback.
Links generated by in-site interaction are reliable: URLs naturally reached through in-site interaction via interactable units from the user's perspective (cards, items, buttons) inherently carry the complete context required by the platform. In contrast, manually constructed URLs may lack implicitly necessary parameters, resulting in being blocked, returning error pages, or even triggering anti-scraping measures.
Browser CDP mode
Connect directly to the user's everyday Chrome through 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 on the user's existing tabs; perform all operations in a background tab that you create yourself, keeping intrusion into the user's environment to a minimum. Without closing the user's tabs, close the tab you created after completing the task, keeping the environment tidy.
Startup
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
The script will check Node.js and the Chrome port in sequence, and ensure the Proxy is connected (if not running, it will start automatically and wait). Once started, 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'
# 捕获页面渲染状态（含视频当前帧）
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: Directly click the interactive unit in the current tab from the user's perspective, simple and direct, processed serially. Suitable for scenarios requiring continuous operations within the same page, such as clicking to expand, turning pages, entering details, etc./new+ full URL: Use the full address of the target link (including all URL parameters) to open it in a new tab. Suitable for scenarios requiring simultaneous access to multiple pages.
Many website links contain session-related parameters (such as tokens), and these parameters are necessary for normal access. When extracting a URL, the full address should be preserved; do not trim or omit parameters.
Media resource extraction
When determining that the content is in an image, use /eval to get the image URL directly from the DOM, then read it in a targeted way—much more precise than a full-page screenshot.
Technical facts
- There is a large amount of content on a page that has been loaded but not displayed—images in carousels that are not the current frame, text in collapsed sections, lazy-loaded placeholder elements, etc. They exist in the DOM but are invisible to the user. Thinking in terms of data structures (containers, attributes, node relationships) allows direct access to this content.
- There are boundaries in the DOM that selectors cannot cross (Shadow DOM's
shadowRoot, iframe'scontentDocument, etc.). Recursive traversal with eval can penetrate all levels at once and return labeled structured content, suitable for quickly understanding the complete structure of an unknown page. /scrollto 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 directly locally and then read; only resources that require a login state to obtain need to be navigated to + screenshotted within the browser.
- Intensively opening a large number of pages in a short time (such as batch
/new) may trigger a website's anti-scraping risk controls. - Prompts such as "content does not exist" or "page not found" returned by the platform do not necessarily reflect the true state; they may also be due to the access method (such as a URL missing required parameters or triggering anti-scraping) rather than the content itself.
Video content acquisition
The user's Chrome renders authentically, 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, enabling discrete sampling analysis of video content.
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 for determining login: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 only inform the user when it is determined that logging in can solve the problem:
"The current page cannot retrieve [specific content] in a logged-out state. Please log in to [website name] in your Chrome, and tell me to continue once done."
After logging in, there is no need to restart anything; just refresh the page and continue.
Task complete
Use /close to close tabs you created yourself; the user's original tabs must be kept unaffected.
The Proxy keeps running; it is not recommended to stop it proactively—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 targets (e.g., researching N projects or N sources at the same time), reasonably dividing the work among sub-agents for parallel execution is encouraged, rather than having the main agent process them serially.
Benefits:
- Speed: With multiple sub-agents 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 only receives summaries, saving tokens
Parallel CDP operations: Each sub-agent, within the current user browser instance, creates the background tabs it needs on its own (/new), operates on its own, and closes them on its own 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-access skill 并遵循指引in the sub-agent prompt; the sub-agent will automatically load the skill, with no need to copy the skill content or specify a path in the prompt. - Sub-agents have autonomous judgment capability. The main agent's job is to clearly statewhat is wanted, and to limithow to do itonly when necessary and certain. Over-specifying steps deprives the sub-agent of judgment space and instead introduces the main agent's erroneous assumptions.Avoid wording in prompts that hints at sub-agent behavior: "search for xx" will anchor the sub-agent to WebSearch, whereas in fact some anti-scraping sites require CDP direct access to the main site to effectively obtain content. When writing prompts, the main agent should describe the goal ("obtain", "research", "understand") 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 |
|---|---|
| Targets are mutually independent, results do not depend on each other | Targets have dependencies; the next needs the previous one's result |
| Each subtask is large enough (multi-page scraping, multiple rounds of searching) | Simple single-page lookup; divide-and-conquer overhead exceeds the benefit |
| Tasks that require CDP browser or long-running execution | Lightweight queries that a few WebSearch / Jina calls can complete |
Information verification tasks
The goal of verification isfirst-hand sources, not more second-hand reports. Multiple media outlets citing the same error creates an illusion of circular corroboration.
Search engines and aggregation platforms are information discovery entry points; they are tools forlocatinginformation, and must not be used to directlyproveAuthenticity. After finding the source, access it directly and read the original text. The same principle applies to researching tool capabilities/usage—official documentation is the primary source; when uncertain, check the documentation or source code first, do not guess.
| Information Type | Primary Source |
|---|---|
| Policy/Regulation | Official website of the issuing agency |
| Corporate Announcement | Company official news page |
| Academic Statement | Original paper/institutional official website |
| Tool capabilities/usage | Official documentation, source code |
When the official website cannot be found: Original reporting by authoritative media (not reprints) may serve as secondary evidence, 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 only a single source, state this to the user as well.
Site Experience
Specific website experience accumulated during operations, stored by domain under references/site-patterns/ .
After determining the target website, if there is a matching site in the site-patterns list output by the pre-check, the corresponding file must be read to obtain prior knowledge (platform characteristics, effective patterns, known pitfalls). Experience content is marked with the discovery date; treat it as a possibly valid hint rather than a guarantee—if operations based on the experience fail, fall back to general patterns and update the experience file.
After CDP operations complete 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 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 |