DOCSEARCHbyAlgolia
Submit Docs

web-access Agent Skill

repository·main·Indexed 27 days ago

https://github.com/eze-is/web-access

An Agent Skill providing AI Agents with full web connectivity and browser automation via the Chrome DevTools Protocol (CDP). It enables interaction with local Chrome or Edge browsers to leverage existing login sessions, handle dynamic content, and perform complex tasks. Features include a CDP Proxy API for tab management, JavaScript execution, real mouse clicks, file uploads, and local browser history/bookmark searching. Supports automatic tool selection between WebSearch, WebFetch, curl, Jina, and CDP.

Tokens
4.2K
Snippets
9
Records
24
Agent score
92%

What's inside web-access

  1. Capabilities of web-access v2.5.2

    main

    The web-access skill provides the following capabilities to AI Agents:

    • Automatic Tool Selection: Automatically chooses between WebSearch, WebFetch, curl, Jina, or CDP based on the scenario.
    • CDP Proxy Browser Operation: Connects to local Chrome/Edge/Chromium browsers to use existing login sessions, support dynamic pages, and perform interactive operations.
    • Advanced Interaction: Supports /click (JS click), /clickAt (real mouse events), and /setFiles (file uploads).
    • Local Resource Retrieval: Uses find-url.mjs to search local browser bookmarks and history (Chrome/Edge) for internal systems or previously visited URLs.
    • Parallel Execution: Distributes multiple targets to sub-agents that share a single Proxy with tab-level isolation.
    • Site Experience Accumulation: Stores operational patterns (URL patterns, platform quirks) per domain to reuse across sessions.
    • Media Extraction: Extracts image/video URLs from the DOM or takes video frame screenshots.

  2. Navigate pages using /click or /new

    main

    When navigating within a site, choose between two strategies:

    1. /click: Clicks an interactive element within the current tab. Best for sequential operations like expanding sections, pagination, or entering details.
    2. /new + Full URL: Opens the target URL in a new background tab. Best for accessing multiple pages simultaneously.

    Important: Always use the full URL including all query parameters. For v2.5.3+, URLs must be passed in the POST body to avoid truncation issues. Do not use the deprecated GET /new?url=... syntax.

  3. Start the web-access skill and check dependencies

    main

    Before using the CDP (Chrome DevTools Protocol) mode, run the dependency check script. This script verifies Node.js, the browser debugging port, and ensures the Proxy is connected (it will automatically start the Proxy if it is not running).

    node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"

  4. Start the CDP Proxy

    main

    The CDP Proxy provides a REST API to control browser tabs via the Chrome DevTools Protocol. It runs at http://localhost:3456.

    To start the proxy manually, run:

    node ~/.claude/skills/web-access/scripts/cdp-proxy.mjs &

    Note: The proxy is intended to run continuously. If you need to force stop it, use:

    pkill -f cdp-proxy.mjs
    node ~/.claude/skills/web-access/scripts/cdp-proxy.mjs &

  5. Select the appropriate web access tool

    main

    Choose a tool based on the task requirements and the nature of the target website:

    ScenarioToolDescription
    Search summaries or keywordsWebSearchDiscover information sources via search engines.
    Known URL, specific info extractionWebFetchFetches content and uses a small model to extract info via prompt.
    Known URL, raw HTML neededcurlRetrieves raw HTML source (useful for meta tags, JSON-LD, etc.).
    Non-public content or anti-scraping sites (e.g., Xiaohongshu, WeChat)Browser CDPDirect browser control; bypasses static scraping layers.
    Login required, interactive tasks, or free navigationBrowser CDPHandles authentication, clicks, and complex navigation.

    Pro-tip: Use Jina (r.jina.ai/example.com) as a pre-processing layer with WebFetch or curl to convert pages to Markdown. This saves tokens but may result in information loss. Limit: 20 RPM.

  6. Configure CDP mode for browser automation

    main

    To use the CDP (Chrome DevTools Protocol) mode, which allows the Agent to control your local browser (Chrome or Edge) and inherit your login sessions, follow these steps:

    1. Requirement: Ensure you have Node.js 22+ installed.
    2. Enable Remote Debugging:
      • For Chrome: Open chrome://inspect/#remote-debugging in your browser.
      • For Edge: Open edge://inspect/#remote-debugging in your browser.
      • Check the box: "Allow remote debugging for this browser instance" (a browser restart may be required).

    Set Browser Preference

    You can fix a default browser in ${CLAUDE_SKILL_DIR}/config.env to avoid being prompted every time.

    Set WEB_ACCESS_BROWSER to either chrome or edge:

    WEB_ACCESS_BROWSER=edge

    Note: If left empty, the Agent will ask for your preference at every startup.

    Temporary Browser Override

    To run a check with a specific browser without changing the config file:

    node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs" --browser chrome
    WEB_ACCESS_BROWSER=edge

  7. Verify CDP mode availability

    main

    Before performing web operations, verify if CDP (Chrome DevTools Protocol) mode is available using the dependency check script.

    Requirements:

    • Node.js 22+ is required for native WebSocket support.

    Handling script exit codes:

    • exit 0: Success. Proceed with operations.
    • exit 2: Browser preference required. Set the WEB_ACCESS_BROWSER environment variable in ${CLAUDE_SKILL_DIR}/config.env to either chrome or edge.
    • exit 1: Error. Check stdout for instructions. If it mentions "Agent processing order", follow the suggested steps (e.g., opening the browser via system command) before retrying.

    Note: If you switch browsers, you must first kill the existing proxy process using pkill -f cdp-proxy.mjs before running the check script again.

    node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"

  8. Implement a sub-agent divide-and-conquer strategy

    main

    When a task involves multiple independent research targets, use sub-agents to perform parallel CDP operations.

    Guidelines for Sub-Agents:

    • Prompting: Sub-agents must include the instruction 必须加载 web-access skill 并遵循指引 (Must load web-access skill and follow instructions).
    • Autonomy: Describe the goal (e.g., "research", "obtain") rather than specific steps (e.g., "search", "scrape") to allow the agent to choose the best method (CDP vs WebSearch).
    • Concurrency: Each sub-agent can create its own background tabs via /new, operate on them using their unique targetId, and close them via /close. They all share the same browser instance and Proxy without race conditions.

  9. Install web-access skill

    main

    You can install the web-access skill using several methods depending on your Agent environment:

    Using npx skills (Recommended)

    If you use the skills CLI, run:

    npx skills add eze-is/web-access

    Using Claude Code

    Install via the Claude plugin marketplace:

    claude plugin marketplace add https://github.com/eze-is/web-access
claude plugin install web-access@web-access --scope user

    Manual Installation

    Clone the repository directly into your Claude skills directory:

    git clone https://github.com/eze-is/web-access ~/.claude/skills/web-access

    Agent-led Installation

    Simply ask your Agent: 帮我安装这个 skill：https://github.com/eze-is/web-access

    npx skills add eze-is/web-access

  10. Extract media and video content

    main

    To extract media efficiently:

    • Images: Use /eval to extract image URLs directly from the DOM rather than taking full-page screenshots. Note that you may need to use /scroll first to trigger lazy-loading for images not yet in the viewport.
    • Videos: Use /eval to control <video> elements (get duration, seek to specific timestamps, play/pause) and combine this with /screenshot to capture specific video frames for analysis.

  11. Troubleshoot CDP Proxy Errors

    main

    Common errors and solutions:

    ErrorCauseSolution
    Chrome 未开启远程调试端口Chrome remote debugging is not enabledOpen chrome://inspect/#remote-debugging and check 'Allow'
    attach 失败targetId is invalid or the tab was closedUse GET /targets to fetch the latest list of valid IDs
    CDP 命令超时The page is not respondingRetry the command or check the tab status
    端口已被占用Another proxy instance is already runningReuse the existing instance

  12. Migrate /new and /navigate endpoints to POST body (v2.5.3+)

    main

    Starting with version 2.5.3, the /new and /navigate endpoints no longer accept the target URL as a query parameter. Using the old GET method with ?url=... will result in an HTTP 400 error.

    To prevent URL truncation (caused by unencoded & or # characters in the target URL), you must now pass the target URL directly in the POST request body as raw data. This ensures that complex URLs (e.g., those from Xiaohongshu, Bilibili, or Weibo containing security tokens) are transmitted without encoding errors.