web-access

web-access スキルの概要

web-access でできること

web-access は、単なるテキスト検索では足りないネットワーク系タスク向けのインストール型ワークフローです。検索を使うべきか、ページを直接取得するべきか、生の HTML を取るべきか、あるいは Chrome DevTools Protocol（CDP）による本物のブラウザ自動化が必要かを、エージェントが判断できるようにします。実運用では、動的ページの読み取り、ログイン必須フローの処理、モダンなサイトからのデータ抽出、通常のプロンプトでは安定して扱えない Web UI 操作などに向いています。

web-access を導入すべき人

この web-access skill は、日常的にエージェントへ次のような依頼をする人に特に向いています。

• 最新情報を検索し、その内容を確認したい
• 要約ではなく実際の Web ページを見たい
• JavaScript 依存の強いサイトにアクセスしたい
• クリック、画面遷移、アップロード、フォーム入力などのブラウザ操作をさせたい
• ログイン状態や実ブラウザのコンテキストが重要なサイトを扱いたい

扱うのが単純な公開情報だけなら、内蔵検索で十分なこともあります。安定した Web 操作まで必要なら、web-access for Browser Automation の適性がより高いです。

実際に解決する課題

多くの人が必要としているのは、抽象的な意味での「ブラウザスキル」ではありません。「このサイトを確認して最新情報を取ってきて」のような曖昧な依頼から、そのサイトで本当に通用する手段へ再現性を持ってたどり着く方法です。web-access の価値は、その判断レイヤーを提供する点にあります。まずは軽い手段から試し、必要に応じて一次情報へ寄せ、ページやフローの都合で本物のブラウザが必要なときだけ CDP へ段階的に上げていけます。

web-access が他と違う点

大きな違いは、単なるブラウザ制御にとどまらないことです。web-access には次の要素がまとまっています。

• ツール選択の戦略
• 実際の Chrome を扱うためのローカル CDP プロキシ
• 自動化を試す前の環境チェック
• プロキシ API のリファレンス
• サイトごとの運用パターンを差し込める仕組み

そのため web-access usage は、特に対象サイトが動的だったり防御的だったりする場合、ただ「Web を見てきて」と投げる汎用プロンプトより実用的です。

導入前に確認すべきこと

導入時の最大のハードルは、環境が整っているかどうかです。web-access install はスキルを追加して終わりではなく、ローカルで使える Chrome のデバッグ環境と、利用可能な Node.js も必要です。ローカルスクリプトを実行できない、あるいは自分の Chrome インスタンスに接続できない場合、このスキルの価値を十分には引き出せません。

web-access スキルの使い方

web-access スキルをインストールする

まず、ローカルの skills ディレクトリにスキルを追加します。

npx skills add https://github.com/eze-is/web-access --skill web-access

続いて、リポジトリが前提としている依存チェックを実行します。

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

ここで特に重要な 2 点を確認できます。

• node がインストールされていること（理想は Node.js 22+）
• Chrome のリモートデバッグが利用可能であること

ブラウザ環境を準備する

リポジトリでは、web-access が Chrome のリモートデバッグに依存していることが明記されています。Chrome で次を開いてください。

chrome://inspect/#remote-debugging

Allow remote debugging for this browser instance を有効にし、必要なら Chrome を再起動します。ここが「スキルは入っている」状態と、「ブラウザ自動化の経路が実際に動く」状態の分かれ目です。

ブラウザ制御が必要なときは CDP プロキシを起動する

実ブラウザとのやり取りが必要なタスクでは、ローカルプロキシを起動します。

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

デフォルトでは、このプロキシは次で待ち受けます。

http://localhost:3456

このプロキシは、タブ作成、画面遷移、評価、クリックなどのブラウザ操作を、シンプルな HTTP エンドポイントとして提供します。これが web-access for Browser Automation の実運用上の中核です。

検索・fetch・curl・CDP の使い分けを理解する

実践的な web-access guide は、タスクを完了できる中で最も軽い手段を選ぶところから始まります。

• 情報源を探す段階では search を使う
• URL が分かっていて抽出済みのページ内容がほしいなら page fetch を使う
• 生の HTML、メタデータ、埋め込みの構造化データが必要なら curl を使う
• ページが動的、ログイン必須、操作中心、または自動化に敏感なら CDP を使う

web-access の本当の強みは、間違った手段で失敗を繰り返すのではなく、どの時点で手法を引き上げるべきかを判断できることです。

web-access をうまく使うための入力

このスキルは、依頼内容に次が含まれているほど性能を発揮しやすくなります。

• 対象 URL またはドメイン
• タスクの目的
• 何をもって成功とするか
• ログインが必要かどうか
• 返してほしい項目や証拠の具体的な指定

弱い入力例:

Check this website.

より良い入力例:

Use web-access to open https://example.com/pricing, confirm the current plan names and monthly prices, and return them in a table with the page title and URL as evidence. If the pricing is loaded dynamically, use browser automation.

後者は、完了条件と、うまくいかない場合の切り替え先の両方をエージェントに示せています。

曖昧な依頼を web-access 向きのプロンプトに変える

信頼しやすいプロンプトの型は次のとおりです。

1. 対象を示す
2. 成功条件を示す
3. 望む証拠を示す
4. 制約があれば示す

例:

Use web-access to inspect the official product page for the latest API pricing. Prefer the official source over summaries. If the page content is JS-rendered or hidden behind interaction, use CDP. Return the exact prices, currency, relevant caveats, and the source URL.

この形が機能するのは、「何を見つけるか」だけでなく、「方法をどう選ぶか」までエージェントに伝えられるからです。

まず読むべきリポジトリ内ファイル

web-access install と実行の流れを短時間で把握したいなら、次の順で読むのがおすすめです。

1. SKILL.md
2. scripts/check-deps.sh
3. references/cdp-api.md
4. scripts/cdp-proxy.mjs
5. README.md

この順番がよい理由:

• SKILL.md では、運用方針とツール選択ロジックが分かる
• check-deps.sh では、実際に何が環境前提になっているかを確認できる
• cdp-api.md では、どんなブラウザ操作が公開されているか分かる
• cdp-proxy.mjs では、ポート、探索方法、互換性などの実装詳細を確かめられる
• README.md では、全体の位置づけをつかめる

必要に応じてプロキシ API を直接使う

リファレンスファイルには、次のような実用的なエンドポイントが載っています。

• GET /health
• GET /targets
• GET /new?url=...
• GET /navigate?target=...&url=...
• POST /eval?target=...
• POST /click?target=...
• POST /clickAt?target=...

ここが重要なのは、web-access skill がブラックボックスではないという点です。エージェントが止まったり詰まったりしたときでも、health を確認したり、タブ一覧を見たり、ページ状態を直接評価したりできます。

実ユーザーの操作に近いケースでは clickAt を優先する

このリポジトリでは、JavaScript の click と、ブラウザレベルの click を明確に分けています。

• click は el.click() を使う
• clickAt は CDP 経由で実際のマウスイベントを発火する

この違いは、ファイルダイアログ、アップロードボタン、一部の bot 対策に敏感な UI で特に効いてきます。通常の click で何も起きないように見えるなら、ブラウザレベルの操作へ切り替えるのは、効果の大きい調整のひとつです。

ドメインに癖があるならサイトパターン照合を使う

補助スクリプトとして次が用意されています。

bash ~/.claude/skills/web-access/scripts/match-site.sh "your task text"

これは references/site-patterns/ を走査し、ドメイン別のガイダンスを探します。最初はこのフォルダの中身が少ないかもしれませんが、同じサイトを繰り返し扱う運用ではかなり有効です。単発のツールではなく、蓄積型の運用プレイブックとしてスキルを育てられます。

web-access の実践ワークフロー

web-access usage の既定フローとして扱いやすいのは次の流れです。

1. 目的と出力形式を明確にする
2. 最適な一次情報源を特定する
3. まず最も低コストな取得方法を試す
4. 描画・ログイン・操作が障害になるなら CDP に切り替える
5. 成功条件を満たしているか確認してから完了する

この流れは、リポジトリの「まず目的を定め、証拠に応じて手段を調整する」という考え方に沿っており、無駄な再試行を減らせます。

web-access スキル FAQ

web-access はブラウザ自動化専用ですか

いいえ。web-access は CDP 自動化だけを指すものではありません。検索、抽出、生 HTML の確認、ブラウザ制御を含む、ネットワーク系タスク全体の判断プロセスを扱います。ブラウザ経路は重要ですが、あらゆる作業を無理にブラウザへ寄せるのではなく、その場に合ったアクセス方法を選べる点こそが、このスキルの有用性です。

普通のプロンプトより web-access が向いているのはどんなときですか

web-access skill を使うべきなのは、タスクがライブなページ、動的レンダリング、インタラクション、または一次情報による確認に依存しているときです。通常のプロンプトでも要件は書けますが、web-access には運用ルール、環境チェック、そして具体的なブラウザ制御経路があります。

web-access は初心者にも向いていますか

はい。ローカルセットアップの手順を追えるなら、初心者にも十分扱えます。このスキルは、どの段階で手法を切り替えるべきかを明確にしてくれるため、むしろ初学者を助けます。難所は概念面より環境構築です。シェルコマンドの実行と Chrome のデバッグ有効化に抵抗がなければ、導入しやすい部類です。

web-access を使わないほうがよいのはどんなときですか

次のようなケースでは web-access を見送るほうがよいです。

• 答えが静的で、すでに分かっている
• 内蔵検索だけで足りる
• ローカルで Node スクリプトを実行できない
• ローカルの Chrome インスタンスを使えない
• そもそもタスクにネットワークアクセスが不要

こうした場合は、セットアップの手間が得られる利点を上回る可能性があります。

web-access には Node.js 22 が必須ですか

推奨は Node.js 22+ です。プロキシがそこでネイティブの WebSocket API を使うためです。リポジトリには、ws モジュールが入っていれば古い Node 向けのフォールバックもありますが、最も素直な構成はやはり Node 22+ です。

web-access はログイン必須サイトにも対応できますか

はい。むしろそれが導入理由のひとつです。実際の Chrome コンテキストを通して動くため、web-access for Browser Automation はセッション状態が重要なサイトに向いています。実際の制約は、そのサイトへローカルブラウザのセッション経由でアクセスできるか、そして必要な操作がプロキシのメソッドで表現できるかどうかです。

web-access は Playwright 系の構成と比べてどうですか

web-access は、より軽量で、エージェントの運用フローに焦点を当てています。フル機能のブラウザテストフレームワークを目指すものではありません。その代わり、小さな HTTP プロキシを通して、ユーザーが今使っている Chrome をエージェントが実用的に操作できるようにし、いつその手段を使うべきかという判断モデルまで含めて提供します。

web-access スキルを改善する方法

web-access に明確な成功条件を渡す

品質を最も左右するのは、全体をむやみに詳しく書くことではなく、完了条件を明確にすることです。web-access には次を具体的に伝えてください。

• どのページやドメインを使うか
• どのデータを返してほしいか
• どんな証拠を含めるか
• どの時点で完了とするか

これだけで、途中で方針がぶれること、無駄に見回り続けること、不完全な抽出で終わることを減らせます。

一次情報から始める

このリポジトリは情報源の質を強く重視しています。検索結果がノイジーなら、公式サイト、アカウントページ、ドキュメント、元のプラットフォーム投稿などへ直接向かうようエージェントに指示してください。この一点だけで、正確さも速度も改善することが少なくありません。

動的ページやブロックされるページでは早めに CDP へ切り替える

よくある失敗は、明らかに実ブラウザが必要なサイトなのに、fetch 系の手法に時間を使いすぎることです。コンテンツが欠けている、要素が見つからない、あるいは JS 依存が強いサイトだと分かっているなら、web-access に早い段階で CDP へ切り替えるよう指示したほうがうまくいきます。

項目単位での抽出依頼を強くする

次のように曖昧に頼むより:

Summarize the page.

次のように依頼してください。

Use web-access to extract the product name, current price, availability, page title, canonical URL, and any visible shipping restrictions.

項目単位の依頼にすると、出力の構造が安定し、検証もしやすくなります。

読み取り目的か操作目的かを分けて伝える

読むことが目的なら、そのように明示します。操作が目的なら、必要な操作を具体的に書きます。プロンプトの中で次を分けて伝えると、スキルの挙動はかなり安定します。

• 情報取得
• 画面遷移
• フォーム入力
• クリックやアップロード
• 操作後の確認

これにより不要なブラウザ操作を防ぎ、web-access usage を予測しやすくできます。

プロンプトを疑う前にプロキシの健全性を確認する

ブラウザ操作が失敗する場合は、まずローカルスタックを確認してください。

curl -s http://localhost:3456/health
curl -s http://localhost:3456/targets

これで、問題がプロンプトにあるのか、ページ側にあるのか、CDP 接続にあるのかを素早く切り分けられます。

再現しやすいセレクタと明示的なページ状態を優先する

対話操作を含むタスクでは、安定した手がかりにひもづくアクションを求めるのが有効です。

• URL
• 画面上に見えるボタンラベル
• フォーム項目の目的
• 成功確認に使えるクリック後のページ変化

プロンプトは、単に「クリックする場所」だけでなく、「クリック後に何が起きるべきか」まで書くと改善します。

サイト知識を継続的に蓄積する

references/site-patterns/ の構造は、実用的な拡張ポイントです。同じドメインを繰り返し自動化するなら、既知のセレクタ、ログイン時の癖、描画遅延、bot 対策の挙動などをここに記録していくと効果的です。これは、毎回ゼロから扱うのではなく、自分の運用に合わせて web-access skill を育てる最良の方法のひとつです。

5 回やり直す前に、1 回目の結果を見て手法を変える

このスキルの思想は、証拠ベースで調整することです。最初のアプローチが失敗したら、言い回しだけを変えるのではなく、手法自体を見直してください。見直しに役立つ問いは次のとおりです。

• そもそも対象の情報源は存在したか
• コンテンツは実際に描画されていたか
• ログインが必要だったか
• その操作は JS click で足りるのか、それとも実際のジェスチャーが必要か
• 求める出力が曖昧すぎなかったか

当てずっぽうの再試行を繰り返すより、短いフィードバックループで修正したほうが結果はよくなります。

重要なタスクでは実装も読む

重要度の高い自動化では、次のファイルに数分目を通す価値があります。

• references/cdp-api.md
• scripts/cdp-proxy.mjs
• scripts/check-deps.sh

これにより、対応エンドポイント、フォールバックの挙動、デフォルトポート、依存関係の前提を実レベルで把握できます。こうした情報は web-access guide の質を実際に高め、導入リスクを下げる種類の情報増分です。