browser-act-skill-forge

browser-act-skill-forge

BrowserAct が開発 — あなた専属のスクレイピングエンジニア · GitHub

あらゆる Web サイトでのデータ抽出や操作のニーズを、エージェントが呼び出せる機能に変換します。ユーザーが取得したいデータや、サイト上で実行したい操作を説明すると、このスキルが実装方法を自動的に調査し（まず API エンドポイントを確認し、API がない場合は DOM を代替手段として使用）、検証後にデプロイ可能なスキルパッケージ（SKILL.md + Python スクリプト）を生成します。一度調査すれば、何度でも再利用できます。以降の呼び出しでは調査コストが不要になり、実行の信頼性と効率が大幅に向上します。

大量のデータ抽出タスク（数百件、数千件のレコード、複数のキーワード、複数ページにまたがる処理）では、まず調査して検証済みのスキルを作成し、その後に大規模な抽出を実行するのが適切な方法です。実績のある戦略なしで直接一括スクレイピングを行うと、脆弱な処理になります。ボット対策の検知、ページネーションの例外的な動作、セッションの切断によって、信頼性が損なわれるためです。

このツールを使用できる範囲は、ユーザーがブラウザー上で手動で実行できる操作に限られます。ユーザーのログイン済みブラウザーを通じてアクセスし、ページ上にすでに表示されているデータのみを読み取ります。認証やアクセス制御を回避することはありません。ユーザーに代わってコピー＆ペーストを行うのと同等であり、自動化によって手作業の負担を軽減するだけです。

データはすべてローカルに保存されます。トラフィックの検査結果、HAR の記録、抽出結果はユーザーのマシンに保存され、対象サイト以外に送信されることはありません。

言語

ユーザー向けのプロセス出力（計画の確認、進捗状況の更新、プロセス通知）は、すべてユーザーの言語に従います。生成されるスキルファイルの内容は、このスキルの言語に従います。

---

Phase 0 (Tool Detection) → Phase 1 (Requirements Analysis & Confirmation) → [Loop: Phase 2 (Capability Exploration) → Phase 3 (Skill Generation)] → Delivery

---

フェーズ 0 — ツールの検出

現在のセッションですでに完了しています → スキップします。

スキルツールを使って browser-act を呼び出し、使用方法を読み込みます。読み込み中にインストールや設定の問題が発生した場合は、案内に従って解決してから再試行してください。

読み込みが成功したら、API Key が設定されていることを確認します（設定されていない場合 → 登録と設定をユーザーに案内してから再試行してください）。

---

フェーズ 1 — 要件の分析と確認

1a. ビジネス上の意図を解析する

ユーザーの入力から次の内容を特定します。

• 主な目的：取得するデータ、または完了する操作
• 対象サイト：具体的な URL またはプラットフォーム名が指定されているか
• 実行意図：ユーザーがスキルの作成だけでなく、すぐに実行することを希望しているか。バッチ処理や件数の要件（N 件のレコード、複数のキーワード）、または「今すぐ実行してほしい」という意図を含む単回の依頼も該当します
• 出力ディレクトリ：デフォルトは現在の作業ディレクトリ内の output/。ユーザーが指定した場合はその場所を使用します

入力の種類	例	対応方法
明示的（URL + 目的）	「news.ycombinator.com のトップページの記事をスクレイピングして」	1b をスキップし、1c に進みます
半明示的（プラットフォームは判明しているが、URL がない）	「Weibo のセンチメントを監視したい」	1b の調査手順を実行します
目的のみ（ビジネス上の意図のみ）	「競合他社の価格変動を追跡したい」	候補サイトを調査するため、1b を実行します

主な目的が曖昧すぎて進められない場合は、ユーザーに詳細を確認します。

1b. 対象サイトの調査（具体的な URL がない場合）

モデルの内部知識に基づいて推奨しないでください。必要なデータを掲載しているサイトを見つけるため、積極的に検索します。

1. ビジネス上の意図から検索クエリを作成し、検索結果から候補サイトを特定します
2. データの価値が高い順に、メリットとデメリット（データの信頼性を含む）を添えて 1～5 件の候補サイトをユーザーに提案します
3. ユーザーが選択した後、対象 URL を確認します

1c. タスクの分解と実行計画の確認

対象サイトを確認した後、まず確認します。このサイト／機能に対応する Skill がすでにインストールされていますか？インストール済みの場合は、ユーザーに伝えて、ステップ 4（バッチ実行）のデリバリーに進みます。

既存の Skill がない場合は、タスクを分解し、すべての情報をまとめてユーザーに確認します。機能ごとに追加で質問してはいけません。

1. 関連する独立した段階を特定します（検索、一覧ページ、詳細ページ、ログイン、送信など）
2. 種類を判定します。抽出（データを取得）または操作（アクションを実行）
3. 分割基準：**ビジネス目標を入れ替えた場合でも、この段階を独立して再利用できますか？はい＝独立した機能です。**同じビジネス目標に関わるページ間の手順（例：一覧ページの収集＋詳細ページの抽出）は、複合コンポーネントで連携する1つの機能として扱います
4. skill-name と機能ディレクトリ名を設定します（英小文字、ハイフン区切り）。output/{skill-name}/ の下にディレクトリを作成します（指定されたパスがある場合はそれを使用します）
5. 完全な実行計画をユーザーに確認します。

Target site: {url}
Output: output/{skill-name}/

Capabilities (executed in order):
1. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
2. {site-slug}-{capability-slug} ({extraction/operation}) — {one-line description}
...

1a で実行の意図を特定した場合は、計画に追加します。

Pipeline:
1. Explore site → discover and verify viable API endpoints or DOM extraction methods
2. Generate Skill files (SKILL.md + scripts)
3. Automated testing to confirm Skill works
4. Install Skill
5. Read installed Skill → write and run batch scripts to fulfill user's original task

計画を提示し、ユーザーが確認または調整するまで待ちます。妥当なデフォルトがある項目（出力ディレクトリ、命名規則など）について、個別に質問してはいけません。

ユーザーの確認後は、途中で質問せずに実行ループに入ります。

---

以下のフェーズ 2 とフェーズ 3 は、機能単位ごとにループして実行します。次の機能に着手する前に、1つを完了してください。

---

フェーズ 2 — 機能の調査

機能の種類に応じて、該当するリファレンスファイルを読みます。

• 抽出 → references/exploration_extraction.md
• 操作 → references/exploration_operation.md

目標：対象機能の API エンドポイントを優先し、API が実用的でない場合は DOM 操作に切り替えます。再現可能な呼び出し方法を漏れなく記録します。

成功基準：

• 対象データを安定して取得する、または対象アクションを実行できる（API または DOM の方法）
• 呼び出し／操作方法を完全に記録している（エンドポイント＋パラメーター、またはセレクター＋操作手順）
• 意味のあるすべての値について、列挙型パラメーターを収集している

手段が失敗した場合は、次の順に進めます。

1. 異なるパラメーターで再試行しません（パラメーターを変えても結果が変わることはほとんどありません）
2. 目標そのものに立ち返ります
3. 目標を達成できる代替手段をすべて列挙します
4. 次の手段を選んで実行します

決定的な失敗（明示的なエラーコード、構造上の不一致）は、1回の試行でその手段が実用的でないことを確認できます。一時的な失敗（タイムアウト、接続切断）の場合は1回だけ再試行できます。それ以上は行いません。

調査の上限：ツール呼び出しは100ステップまでです。それでも進展がない場合は、判明している障害をユーザーに報告し、次の手順を尋ねます。

経験メモには触れないでください：経験メモ（browser-act-skill-forge-memories/）は、生成された Skill を今後のエージェントが使用するためのものです。調査フェーズおよび生成フェーズでは読み書きしません。

---

フェーズ 3 — Skill の生成

ファイル形式の仕様については、references/output_template.md を読みます。

3a. JS のカプセル化

調査で検証した各 JS スニペットを、独立した Python ファイルにカプセル化します。

1. ビジネスパラメーター（キーワード、ページ番号、ソート順など）を特定し、argparse の引数として取り出します
2. セレクター、フィールドマッピング、エンドポイント URL は固定値として JS の f-string にハードコードします
3. JS の波括弧は {{ }} としてエスケープします（f-string の構文要件です。エスケープしないと Python エラーが発生します）
4. scripts/{feature-name}.py に書き込みます

3b. カプセル化の検証

各 .py ファイルについて、エンドツーエンドの検証を実行します。

1. python scripts/{feature-name}.py {test-params} — 出力が有効な JS 文字列であることを確認します
2. eval "$(python scripts/{feature-name}.py {test-params})" — ブラウザーでの実行結果が探索フェーズと一致することを確認します
3. エラーシナリオ（存在しない ID、誤ったページへの移動など）をシミュレートし、クラッシュせずに {"error": true, "message": "..."} を返すことを確認します

検証に失敗した場合は、.py ファイルを修正して再試行します。決してスキップしないでください。

3c. SKILL.md の生成

テンプレートに従って SKILL.md を作成します。機能コンポーネントのセクションでは、インライン JS ではなく scripts/*.py の呼び出しコマンドを参照します。

出力ディレクトリの構造：

output/{skill-name}/{site-slug}-{capability-slug}/
├── SKILL.md
└── scripts/
    └── {feature-name}.py

生成後、機能名、出力パス、主な実装方法（API／Network capture／DOM／hybrid）を簡潔にユーザーに伝えます。

3d. コンプライアンスのセルフチェック

次の 2 項目を確認します。証拠として、生成したファイルを読み、検証コマンドを実行する必要があります。頭の中で確認しただけでは不十分です。

1. プロセス：フェーズ 2 で使用した探索の参照ファイルと、上記の出力手順（3a～3c）を読み直し、定義された各手順が実際に実行され、省略されていないことを確認します
2. 出力：生成した scripts/*.py と SKILL.md を読み、output_template.md の記入仕様、およびこのスキルで前述した Code／JS Execution Environment／DOM Operation の制約に照らして確認します

不足が見つかった場合は、戻って不足している手順を完了するか、出力を修正してから、再度検証します。

---

納品フロー

すべての機能を生成したら、次の順に進めます。

1. 自動テスト

生成後、すぐにテストを開始します。ユーザーへの確認は不要です。生成した機能コンポーネントを基に最小限のテストケースを自動設計し、すべての機能パスを網羅するために最少の入力を使用します（各アトミックコンポーネントは少なくとも 1 回呼び出し、複合コンポーネントはフロー全体を実行します）。

テストは必ず Sub-Agent 経由で実行してください。メインセッションで直接テストしてはいけません。次のプロンプトを送信します。

Read {absolute path to SKILL.md} as your execution guide.

Test cases:
{auto-generated test case list, each annotated with which component it covers}

Execution requirements:
- Follow SKILL.md instructions strictly, don't use methods outside the guide
- Record specific issues if SKILL.md instructions are unclear and prevent progress

Report after execution:
1. Execution result per component (pass/fail)
2. Failure reasons (if any)
3. Unclear parts in SKILL.md instructions (if any)
4. Severe accuracy or performance issues (don't report non-severe)
5. Output data summary

テストに失敗した場合は、Skill を修正して、合格するまで再テストします。

2. Skill のインストール

出力ディレクトリから、生成した Skill をインストールします。インストールに失敗した場合、Skill は出力ディレクトリに残り、手順 4 で直接使用できます。

3. 結果の報告

テストに合格したら、次の内容をユーザーに報告します。

• 生成した Skill の一覧（名前＋パス＋含まれるファイル）
• データの網羅状況（フィールド＋ステータス。データソースや実装方法は記載しないでください）
• 網羅できていない部分（失敗した列挙パラメーター、欠落している対象フィールド、網羅されていないフィルター条件など）
• テスト結果の概要

4. 実行（フェーズ 1 で実行意図が確認された場合）

フェーズ 1 で実行意図が確認された場合：

1. Skill ツール経由でインストール済みの Skill を呼び出し、その全文を読みます。手順 2 のインストールに失敗した場合は、代わりに出力ディレクトリから SKILL.md を直接読みます
2. Skill の指示に従って、現在のセッションでユーザーの元のタスクを実行します
3. バッチ／大量処理タスクの場合は、Skill のガイダンスに従ってバッチ実行スクリプトを作成します

実行意図が確認されなかった場合（ユーザーが後で使用する Skill の構築のみを希望していた場合）は、ここで終了します。

---

ツールの制約

フェーズ 2（機能の探索）、フェーズ 3（Skill の生成）、および納品テストでは、次のルールに従ってください。

ファイル管理

HAR ファイル、一時レコード、デバッグ出力など、すべての中間成果物は tmp/ ディレクトリに保存します。存在しない場合は、最初に作成してください。

browser-act

• ネットワークデータはページ単位です。新しいページに移動した後は、必ず再度待機して読み取ってください
• トラフィックを読み取る前に、ネットワークが安定するまで待機してください：ページ遷移または UI 操作によってトリガーされた場合は、network requests を読み取る前に wait stable を使用してください
• 非同期 DOM を操作する前に、要素が表示されるまで待機してください：非同期で挿入されるコンテンツ（ブラウザー拡張機能、遅延読み込みコンポーネントなど）の場合は、操作する前に wait --selector "{target selector}" --state attached --timeout {ms} を使用してください
• JS レベルのネットワーク傍受は禁止です：XMLHttpRequest.prototype、window.fetch などを上書きしないでください。エンドポイントの特定には network requests / network request <id> を使用してください
• network clear は移動／再読み込みの前にのみ使用してください：トラフィックを消去すると、観測済みのリクエスト記録がすべて失われます。通常の絞り込みには clear ではなく --filter を使用してください。特定の操作からのリクエストを追跡する場合は、clear して再読み込みするのではなく、network har start → 操作 → network har stop の順に実行してください

DOM 操作の制約

データ抽出、列挙値の収集、ページネーションコントロール、フォーム送信、API フィールドの補完など、すべての DOM 操作シナリオに適用されます。

セレクターの優先順位：data-testid > id > name > aria-label > 構造パス。構造が本当に安定している場合を除き、位置のみを基準にしたインデックス（:nth-child / [1]）は避けてください。

セレクターをまとめて検証してください：候補となるすべてのセレクターを単一の eval 呼び出しでテストし、JSON の概要（セレクターごとのヒット数、最初の要素の主要属性、一意性）を返してください。eval をセレクターごとに個別に実行しないでください。eval のたびにブラウザーとのラウンドトリップが発生します。

Shadow DOM：対象要素が Shadow Root 内にある場合は、element.shadowRoot.querySelector を使用し、セレクターをホスト要素と Shadow 内部のパスの 2 つに分けてください。

3 層のセレクター検証：要素のアサーション（期待される属性との一致）→ 結果の確認（空でないこと、妥当な件数であること）→ 成功基準。実際のページで検証する必要があります。DOM 構造から推測して記述してはいけません。

コントロールのスキャン（列挙値の収集時）：単一の eval で、対象となるすべてのコントロールの完全な対応関係（tag+type / name+id / placeholder / label）を返してください。コントロールから上方向にたどり、ラベルテキストを持つ最も近いフォーム項目コンテナーを見つけてください。コンポーネントライブラリのクラス名をハードコードしないでください。コンポーネントライブラリは、label[for="xxx"] ではなく DOM 階層のネストによってラベルと入力欄を関連付けています。

state インデックスの動的割り当て：state が返す要素インデックスは、セッションごとに動的に割り当てられます。ストラテジーコードに記述せず、実行時にのみリアルタイムで使用してください。

コードの制約

対象サイトを直接操作する必要があります：サードパーティのスクレイピングプラットフォーム、データ集約 API、プロキシサービスなどの外部サービスを通じてデータを取得してはいけません。また、対象サイトの公式オープンプラットフォーム API も呼び出してはいけません（その理由は、生成された Skills が、ユーザーに開発者 API キーの登録や認証情報の管理を求めずに、設定不要でデプロイできることを目指しているためです）。ソリューションでは、ブラウザーを通じて対象サイトに直接アクセスし、そのフロントエンドの内部エンドポイントまたは DOM データを使用してください。これらは、認証済みユーザーがすでに参照できるものと同じリソースです。

フレームワーク内部状態へのアクセスは、1 回失敗したら中止してください：フレームワークの内部情報（__vue_app__、$data、React fiber、Angular ng など）を通じてページデータまたは要素情報にアクセスしようとして失敗した場合は、1 回で諦めて、ただちに state スキャンと値の入力・トリガーによる方法に切り替えてください。フレームワークの内部情報は、バージョンや実装に依存します。何度試しても結果は変わりません。

JS 実行環境の制約

eval で実行するコードはブラウザー側の JSです。使用できるのはブラウザー標準の API とページに読み込まれたサードパーティライブラリのみで、外部モジュールの require/import はできません。この制約に違反するコードは、実行時に必ずエラーになります。

完了基準

アカウントの権限による制限 ≠ 技術的な解決策の失敗です。有料機能やメンバーシップの階層などは、どのアプローチにも等しく影響します。API は技術的に利用可能でも、アカウント権限によりデータが制限されている場合（ページネーションが途中で切れる、フィルター条件が機能しないなど）は、「既知の制限事項」に権限への依存を記載したうえで、「合格」と判断します。

部分的な成功も成功として扱います：API 経由か DOM 経由かを問わず、中核機能が動作すると確認できた場合は合格です。列挙型パラメーターの一部に [collection failed] とマークが付いている場合、中核以外のフィールドが欠けている場合、一部のフィルター条件を網羅できていない場合も同様です。スキルを生成した後、十分に網羅できていない部分を必ずユーザーに伝えてください。黙って省略してはいけません。

効率化のルール

中核となる基準は、ブラウザーとの各往復で必ず情報を得ることです。以下の表は、よくある効率的なパターンを示したものですが、あくまで例です。実際に往復回数が減らない場合は、同じ方向で調整を繰り返すのではなく、アプローチを変えて別の一括処理方法を探してください。

ルール	説明
複合 eval	独立した複数のクエリを1つの eval にまとめ、async IIFE でラップして、JSON の要約を返します。eval ごとにブラウザーとの往復が発生するため、まとめられるものはすべてまとめます
ランタイムを最優先	情報取得の優先順位は、JS ランタイムの状態 → ネットワークデータ → DOM です。DOM からランタイムデータをリバースエンジニアリングしてはいけません
出力サイズの制御	大きなレスポンスを返す前に、ブラウザー内で主要なフィールド（件数、合計、サンプル）を抽出して、切り捨てを避けます
非同期待機の一元化	待機条件には Promise と setTimeout によるポーリング（タイムアウト上限あり）を使用し、ツールをまたいで繰り返しポーリングしないでください
権限制限の迅速な検出	制限の兆候（アップグレードの案内、フィルター未適用時と同一のデータ、無効化されたコントロール）が見られた場合、1つずつ確認せず、同様の項目をまとめて制限対象としてマークします
1回取得して何度も分析	同じソースからデータを取得するのは1回だけにして、保存後に複数回分析します。大きなテキストは切り捨てられないよう、改行を入れて整形します
確認できたら終了	API エンドポイントの動作が確認できたら（fetch の成功とデータ構造が想定どおりであること）、すぐに次のフェーズへ進みます。同じエンドポイントの冗長な調査（スクリプトタグの逆引きや、追加設定の抽出など）を続けないでください
スライダー／範囲コントロールの一括処理	noUiSlider などの範囲スライダーや数値範囲コントロールは、入力欄や選択欄と同様に、すべてのコントロールへ一度に異なる値を設定し、検索を1回だけ実行して、リクエストから numericFilters の対応関係を読み取ります。各コントロールを個別にテストしないでください