web-access

web-access Skill

First-time installation

When the user uses it for the first time, execute the following process:

Step 1: Run environment detection

bash ~/.claude/skills/web-access/scripts/check-deps.sh

Step 2: The AI handles missing dependencies based on the output

The detection script only reports facts; installation decisions are made by the AI. Install whatever is missing; when Chrome is missing, prompt the user to download it manually (it cannot be installed automatically).

Step 3: After installation is complete, explain the following to the user

web-access is ready. For any networked need, just say it directly, and I will automatically choose the most suitable method:

Only need search results → search directly, fastest

Need to view the full page → scrape the page content without launching a browser

Need login or a dynamic page → automatically launch the browser, and after logging in once, it is persistently saved

Windows users need a Git Bash environment (just install Git for Windows).

Browsing philosophy

Browse like a human, not execute a program like a robot.

When humans browse web pages, they do not list complete steps before starting; instead, they enter with a goal, judge as they look, solve obstacles when encountered, and go deeper when they find the content is insufficient—making decisions throughout around "what do I want to get." All behavior of this skill should follow this logic.

Three core judgments:

① What do I need? — Task-driven: first think clearly about the nature of the target information, then choose the lightest method that can reach it directly. Do not use heavy tools for lightweight tasks, and do not use lightweight tools for content they cannot cover.

② Is it enough? — If the information obtained can complete the task, it is enough. Do not over-collect, and do not waste cost for the sake of "completeness." To roughly understand a video, a few frames are enough; to understand an article, reading the text is enough; there is no need for full-page screenshots to do something that can be done with the accessibility tree.

③ What to do when encountering an obstacle? — Solve it within the layer, do not fall back, and do not disturb the user. Pop-ups, login walls, ads, load failures—judge like a human whether this obstacle really blocks the target content: if it blocks it, handle it; if it does not, bypass it and continue. Only inform the user when it is confirmed that it cannot be solved on your own.

Information acquisition channel selection

Evaluate the task first, then choose the channel: Decide the starting point based on "the nature of the target information and what tool can obtain it directly," and choose the lightest and most direct solution.
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 there is no qualitative improvement after multiple search attempts, upgrade to a more fundamental acquisition method: locate first-hand sources (official websites, official platforms, original pages).

Scenario	Channel
Only need search summaries or keyword results, or need to discover information sources	WebSearch
URL known, static public page	WebFetch
Social media, content platforms (WeChat Official Accounts, Weibo, Xiaohongshu, X/Twitter, etc.)	Browser CDP(Direct, skip WebFetch)
Needs dynamic content, logged-in state, interactive operations, or needs 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.

Add header when requesting with WebFetch Accept: text/markdown, text/html, websites supporting this protocol return Markdown directly, saving about 80% of tokens. When it fails (empty content / 403 / JS rendering), escalate to the browser layer.

No downgrading: after entering a heavier channel, you must not go back and use a lightweight tool to accomplish the same goal—that is equivalent to retreading a known blocked path. Obstacles encountered at the browser layer should be resolved within that layer (e.g., handling login), not by going back. The only exception: new sub-goals derived during browser operations may re-select a channel.

After entering the browser layer, distinguish the nature of the task:

Operational(navigation, form filling, clicking): use the accessibility tree to perceive the interface, and only use screenshots as an aid when it cannot be recognized
Content-oriented(reading posts, viewing news, analyzing pages): use the accessibility tree to read the text structure, and at the same time judge whether images carry core information—if so, extract the image URLs and read them in a targeted way

Image judgment: for social media, image-and-text blogs, and screenshot-type content, images are valuable by default, so actively fetch them; for tool-type and navigation-type pages, the accessibility tree is sufficient by default.

Browser CDP mode

Startup

bash ~/.claude/skills/web-access/scripts/ensure-browser.sh

Browser ready on port 9222 → started by the script itself, state is trustworthy, use it directly (close after the task ends)
already running → residual process detected, state is untrustworthy, must verify: run agent-browser --cdp 9222 open about:blank, if successful it is usable; if it fails, execute close and then ensure again (do not close after the task ends)
ERROR or agent-browser is unresponsive → execute bash ~/.claude/skills/web-access/scripts/close-browser.sh and then run again

⚠️ Downgrading is strictly prohibited: only use agent-browser CDP mode, do not switch to other browser tools. Playwright MCP is also based on playwright-core + launchPersistentContext at the underlying level, with equivalent capabilities, but the profile path is different—switching will lose the existing logged-in state and require logging in again.

Common commands

agent-browser --cdp 9222 open <url>           # 打开页面
agent-browser --cdp 9222 snapshot -i          # 可交互元素（操作用）
agent-browser --cdp 9222 snapshot             # 完整无障碍树（读文字用）
agent-browser --cdp 9222 click @ref-123       # 点击元素
agent-browser --cdp 9222 fill @ref-123 "内容" # 填写输入框
agent-browser --cdp 9222 wait load networkidle  # 仅用于 click/fill 触发导航后；open 已内置等待，勿在 open 后使用
agent-browser --cdp 9222 scroll down 3000     # 触发懒加载
agent-browser --cdp 9222 screenshot /tmp/x.png
agent-browser --cdp 9222 screenshot --annotate      # snapshot -i ref 失效时的升级方案，见 references/commands.md
agent-browser --cdp 9222 eval "<js>"          # 执行 JS，用于提取 DOM 信息

Image extraction

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

Two technical details you need to know:

Lazy loading: for images not yet in the viewport, naturalWidth is 0; before eval, scroll to the bottom first to get the complete list
Filter noise：naturalWidth > 200 exclude icons and avatars, keep content images

agent-browser --cdp 9222 scroll down 3000
agent-browser --cdp 9222 eval "JSON.stringify(Array.from(document.querySelectorAll('img')).map((img,i)=>({i,src:img.src,w:img.naturalWidth,h:img.naturalHeight})).filter(x=>x.w>200))"
# 对每张目标图片：
agent-browser --cdp 9222 open <img_url>
agent-browser --cdp 9222 screenshot /tmp/img_n.png
# 用 Read tool 读取截图内容

Video content acquisition

In CDP headed mode, the browser truly renders, and screenshots can capture the current video frame. Core capability:seek to any point in time and take a screenshot, enabling discrete sampling analysis of video content.

# 获取总时长，制定采样计划
agent-browser --cdp 9222 eval "document.querySelector('video').duration"
# seek + 播放 + 截图
agent-browser --cdp 9222 eval "var v=document.querySelector('video'); v.currentTime=60; v.play()"
sleep 2
agent-browser --cdp 9222 screenshot /tmp/frame.png
# 全屏截图画面更清晰
agent-browser --cdp 9222 eval "document.querySelector('video').requestFullscreen()"

Frame sampling granularity (for reference only; analyze specific videos on a case-by-case basis: rough understanding → 30-60s intervals; understanding narrative → 10s; fine-grained analysis → 1-2s) is determined by the task requirements yourself, with no need for the user to specify.

Login judgment

There is only one core question in login judgment:Have you obtained the target content?

After opening the page, first try to obtain the target content and keep executing. During this process, make judgments based on two aspects of information:

Domain knowledge: Knowledge about the website—X/Twitter's latest timeline, Xiaohongshu's private content, Weibo's complete comments, etc. This type of content usually requires login to obtain complete data
Actual page feedback: Does the content match expectations? Is it a degraded version (e.g., popular posts instead of latest posts)? Are there obvious omissions?

Even if the page shows a login prompt, as long as the target content has been obtained, there is no need to bother the user to log in.

Only when it is confirmed thatthe target content cannot be obtained, infer: Can logging in solve this problem? If the inference holds, tell the user:

"The current page cannot obtain [specific content] in a logged-out state. Please log in to [website name] in the already opened Chrome window, and tell me to continue after completing it."

After logging in, there is no need to restart the browser; directly continue the original task.

Task ends

ensure-browser.sh returns Browser ready(this launch) → close the browser (this script must be used; do not kill directly, otherwise a crash window will be left behind）：

bash ~/.claude/skills/web-access/scripts/close-browser.sh

Special task rules

Verification task

The target of verification isprimary sources, not more secondary reports—multiple media outlets citing the same error can create an illusion of circular corroboration.

Search is used tolocatesources, not toproveauthenticity. After finding the source, directly visit and read the original text.

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

When the official website cannot be found: Original reporting by authoritative media (not reprints) can serve as secondary evidence, but it must be explained to the user: "The official original text was not found. The following verification comes from a [media name] report, and there may be transcription errors."

Understanding the boundaries of tool capabilities

When there are doubts about the capabilities of any tool (MCP, CLI, library),if there is not enough knowledge to be certain, first check the official documentation; if there is insufficient documentation, consider checking the source code, and then make a judgment, do not guess, and do not shift uncertainty to the user.

References index

File	When to load
`references/commands.md`	When uncommon commands are needed (drag, storage, pdf, etc.)
`references/login-flow.md`	When details of the login process need to be understood