autobrowse

AutoBrowse — 自己改善型ブラウザースキル

反復的な実験を通じて、信頼性の高いブラウザー自動化スキルを構築します。内側のエージェントがサイトを閲覧し（evaluate.ts）、外側のエージェントであるあなたが実行結果を確認して、手順（strategy.md）を改善します。安定して合格するまで繰り返します。

エントリーポイント

起動方法は柔軟です。明示的なフラグでも、自由形式の自然言語でも実行できます。

/autobrowse --task google-flights
/autobrowse --task google-flights --iterations 10 --env remote
/autobrowse --task google-flights --browser-trace
/autobrowse --tasks google-flights,amazon-add-to-cart
/autobrowse --all

# Also fine — parse freely:
/autobrowse https://flights.google.com/
/autobrowse book a flight on delta.com
/autobrowse fix the existing google-flights skill

--browser-trace（デフォルトでは無効、リモート環境専用）：各イテレーションを同階層のbrowser-traceスキルと連携させ、内側のエージェントをCDPキャプチャでラップして、ページごとのネットワーク／コンソール／ページライフサイクルの証拠を取得します。--env remoteが暗黙的に指定されます。--env localと併用するとエラーになります。同階層にbrowser-traceスキルが${CLAUDE_SKILL_DIR}/../browser-trace/に存在し、環境変数BROWSERBASE_API_KEYが設定されている必要があります。

ユーザーが--task <name>の代わりにURLまたは自由形式の指示を渡した場合：

• ${WORKSPACE}/tasks/にサイトや目的が明確に一致する既存のタスクがあれば、それを使用します。
• それ以外の場合は、短いケバブケースの名前を選び、${CLAUDE_SKILL_DIR}/references/example-task.mdを元に${WORKSPACE}/tasks/<name>/task.mdを作成して、ユーザーの発言に基づいてURLと目標を記入し、続行します。選択した名前を1行でユーザーに伝えます。

---

実行方法

ステップ1 — 引数を解析して状況を把握する

渡された内容を確認します：

• --task <name> → 単一タスクモード
• --tasks a,b,cまたは--all → 複数タスクモード（サブエージェントを起動）
• --iterations N → evaluate → improveサイクルの回数（デフォルト：5）
• --env local|remote → ブラウザー環境（デフォルト：local。ボット対策されたサイトではremoteを使用）
• --browser-trace → browser-trace連携を有効化（デフォルトでは無効）。--env remoteが暗黙的に指定されます。--env local --browser-traceが両方とも明示的に渡された場合は、browser-trace requires Browserbase; drop --env local or drop --browser-trace.というエラーを返します。

ユーザーが自由形式のテキストを渡した場合は、続行する前に上記のいずれかに対応付けます。

ステップ2 — ワークスペースを設定する

すべてのトレーニング成果物（タスク定義、手順のイテレーション、トレース、レポート）は、~/.claude/skills/の内側ではなく、現在の作業ディレクトリにあるワークスペースディレクトリに保存されます。これにより、内側のエージェントによるファイル書き込みをClaudeのホームディレクトリの外に保ち、権限に関する問題を避けられます。

デフォルトのワークスペース：${CWD}/autobrowse/

mkdir -p ./autobrowse/tasks ./autobrowse/traces ./autobrowse/reports

タスクディレクトリ（./autobrowse/tasks/<task>/task.md）がまだ存在しない場合は、ひな形を作成します：

mkdir -p ./autobrowse/tasks/<task>
cp ${CLAUDE_SKILL_DIR}/references/example-task.md ./autobrowse/tasks/<task>/task.md
# Then edit task.md to describe the URL, inputs, steps, and expected JSON output

${CLAUDE_SKILL_DIR}にあるスキルのソースは読み取り専用のままです。トレーニング中に書き込みが行われるのは、CWD内の./autobrowse/だけです。最終ステップの昇格では、~/.claude/skills/<task>/SKILL.mdに単一のファイルを書き込みます。

利用可能なタスクを一覧表示します：

ls ./autobrowse/tasks/

ステップ 3 — マルチタスク：並列サブエージェントを起動する

複数のタスクを実行する場合は、Agent ツールを使用してタスクごとに 1 つのサブエージェントを同時に起動します。各サブエージェントには、そのタスクの autobrowse ループ全体を実行するための自己完結型プロンプトを渡します。

「タスク <name> の autobrowse スキルを実行します。ワークスペース：<absolute-path-to-workspace>（例：/path/to/project/autobrowse）。次の手順を <N> 回繰り返してください：評価 → トレースを読む → strategy.md を改善 → 繰り返す。--env <env> を使用してください。すべての evaluate.mjs の呼び出しに --workspace <workspace> を指定してください。親の呼び出しで --browser-trace が使用された場合は、すべてのイテレーションで SKILL.md ループのトレースパスのブロックを必ず使用してください（セッションを事前作成し、bb-capture をアタッチし、evaluate.mjs に --connect-url を渡し、停止して bisect し、解放する）。デフォルトの単一コマンドパスに切り替えないでください。autobrowse ループの手順に正確に従ってください。

スキルとして昇格させる際は、適切な agentskills frontmatter（name と description）を付けて、~/.claude/skills/<task-name>/SKILL.md にインストールしてください。strategy.md をコピーするだけにせず、自己完結型のスキルを作成してください。

最後に、次の情報を含む構造化された概要を出力してください：タスク名、最終実行の合否、累計コスト、完了したイテレーション数、イテレーションごとの表（イテレーション番号、ターン数、コスト、ステータス、検証した仮説）、および学びの要点 2～3 件。」

すべてのサブエージェントを並列で起動し、完了するまで待ってから、各サブエージェントの概要を集めてセッションレポートを作成します。

単一タスクの場合はこのステップを省略し、以下のループを直接実行します。

---

ループ（各タスクで実行）

イテレーション開始時

./autobrowse/tasks/<task>/task.md が存在することを確認します（存在しない場合は、ステップ 2 を参照してテンプレートから作成します）。strategy.md は初回実行時にハーネスによって空の状態で自動作成されます。

要件

環境内、または CWD の .env ファイル内に ANTHROPIC_API_KEY が必要です（evaluate.mjs が自動的に読み込みます）。見つからない場合、ハーネスは明確なエラーを出力して終了します。他のパスにキーがないか探さないでください。

内側のエージェントを実行する

デフォルトパス（--browser-trace なし） — オーケストレーションなしの単一コマンド：

node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse
# or for bot-protected sites:
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse --env remote

これによりブラウザーセッションが実行され、完全なトレースが ./autobrowse/traces/<task>/latest/ に書き込まれます。

トレースパス（--browser-trace、リモートのみ） — 外側のハーネスが Browserbase セッションを事前作成し、bb-capture をパッシブオブザーバーとしてアタッチしてから、セッションの connectUrl を evaluate.mjs に渡します。これにより、すべての内側の browse 呼び出しで --cdp $connectUrl --session autobrowse-main が使われます（オブザーバーが Network/Console の全イベントを取得できる標準的な browser-trace パターンです）。$N に 1 から始まるイテレーション番号を設定して、このブロックをイテレーションごとに 1 回実行します。

# Preflight — fail fast if browser-trace isn't installed alongside autobrowse.
BT_DIR="${CLAUDE_SKILL_DIR}/../browser-trace"
if [ ! -f "$BT_DIR/scripts/bb-capture.mjs" ]; then
  echo "ERROR: --browser-trace requires the browser-trace skill at $BT_DIR." >&2
  echo "Install it by cloning github.com/browserbase/skills and copying skills/browser-trace/" >&2
  echo "into the same parent directory as autobrowse (e.g. ~/.claude/skills/browser-trace/)." >&2
  exit 1
fi

# a. SESSION SETUP — pre-create the keep-alive session and derive its connectUrl
sid=$(browse cloud sessions create --keep-alive --verified --proxies \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).id))")
connect_url=$(browse cloud sessions get "$sid" \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).connectUrl))")

RUN_ID="run-$(printf '%03d' "$N")"
TRACE_ROOT="./autobrowse/traces/<task-name>/$RUN_ID"
mkdir -p "$TRACE_ROOT"
export O11Y_ROOT="$TRACE_ROOT/.o11y"   # park browser-trace output inside the autobrowse run dir
export O11Y_RUN_ID="$RUN_ID"           # tells the browse CLI which run dir to write descriptors.ndjson into

# b. ATTACH BROWSER-TRACE — passive observer; runs in background
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bb-capture.mjs "$sid" "$RUN_ID" &
sleep 2

# c. RUN AUTOBROWSE — connectUrl flag tells evaluate.mjs to inject --cdp/--session
#    into every inner browse call. The inner agent never sees --remote.
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs \
  --task <task-name> --workspace ./autobrowse --env remote \
  --connect-url "$connect_url" --run-number "$N"

# d. STOP + BISECT + UNIFY — order matters; bisect needs the session to still
#    exist, and unify-trace joins the bisect output with autobrowse's trace.json
#    into a single time-ordered NDJSON the outer agent reads first each iter.
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/stop-capture.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bisect-cdp.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/scripts/unify-trace.mjs \
  --trace-dir "$TRACE_ROOT" \
  --o11y-dir "$O11Y_ROOT/$RUN_ID"

# e. RELEASE
browse cloud sessions update "$sid" --status REQUEST_RELEASE

内側のエージェントのトレースは ./autobrowse/traces/<task-name>/latest/ に、CDP の bisect は ./autobrowse/traces/<task-name>/latest/.o11y/<run-id>/ に書き込まれます。トレース付きの browse CLI は、コマンドごとのリッチなノード記述子も .o11y/<run-id>/cdp/descriptors.ndjson に出力します（ページを操作する呼び出しごとに、対象の tag/id/role/accessibleName/attributes/xpath/bounding-rect を含む JSON オブジェクトが 1 つ出力されます）。記述子ファイルは後続のコード生成に使われますが、仮説の立案には必要ありません。トレースを読む際は無視してください。

トレースを読む

cat ./autobrowse/traces/<task-name>/latest/summary.md

サマリーには、所要時間、コスト、ターン数、判断ログ、最終的な JSON 出力が記録されています。

エージェントが失敗したり、行き詰まったりした場合は、さらに詳しく確認します。

• ./autobrowse/traces/<task-name>/latest/trace.json を読み、失敗したターンを検索します
• Read ツールで、失敗した時点の前後のスクリーンショットを読みます

--browser-trace を使用した場合は、unified-events.jsonl から確認を始めます。 ハーネスは、エージェントのターンログとブラウザーの CDP の大量のイベントを、実行ルートにある時系列順の NDJSON ストリームにまとめます。ファイルは 1 つで、source: "agent" | "browser" のようにソースがタグ付けされ、壁時計のタイムスタンプ順に交互に記録されています。上から順にざっと確認してください。失敗の原因は、たいてい隣接する 1、2 行にあります（エージェントがコマンド X を実行し、ブラウザーが Y を返した、という具合です）。

cat ./autobrowse/traces/<task-name>/latest/unified-events.jsonl

構造化ファイル（trace.json、.o11y/<run-id>/cdp/*）も、統合ストリームから詳細を確認する必要がある箇所がわかった場合に、掘り下げて調べるためにエージェントが利用できます。

必要な情報	詳細確認用のファイルまたはコマンド
ページごとの合計値とタイミング（イベント、ネットワーク数、ページごとのエラー）	.o11y/<run-id>/cdp/summary.json
失敗したネットワークリクエストの一覧	.o11y/<run-id>/cdp/network/failed.jsonl
コンソール例外の完全なペイロード（スタックトレースなど）	.o11y/<run-id>/cdp/console/exceptions.jsonl
ページごとの範囲（ページ N のイベントのみ）	.o11y/<run-id>/cdp/pages/<pid>/
特定ターンの完全な推論テキスト／省略されていないツール出力	trace.json（turn === N でフィルタリング）
任意のグループ化クエリ（ホストの上位一覧、ページごとのエラーなど）	O11Y_ROOT=./autobrowse/traces/<task-name>/latest/.o11y node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/query.mjs <run-id> <cmd>

統合ストリームを標準として使い、グループ化クエリ、完全なテキストペイロード、またはストリームではできないフィルタリングが必要な場合にのみ、構造化ファイルを詳しく調べます。

仮説を立てる

問題が起きた正確なターンを見つけます。問題を防げたはずのヒューリスティックを 1 つ挙げるとしたら、何でしょうか？

--browser-trace を使用した場合、仮説には unified-events.jsonl 内の具体的なイベント（行番号またはタイムスタンプ）を記載する必要があります。ファイルを掘り下げて調べた場合は、調べたファイル名を記載します。これにより、根拠に基づいた更新ができ、単なる印象に頼らずに済みます。エージェントのコマンドだけに基づく仮説は「クリックが機能しなかった」かもしれませんが、統合ストリームに基づけば「unified-events.jsonl の 47 行目：browse open の後、/api/checkout でステータス 403 の Network.responseReceived が記録された — --verified --proxies に切り替える」と言えます。

例：

• 「ドロップダウンをクリックした後、1 秒待ちます。選択肢はアニメーション表示された後でないとクリックできません」
• 「ランディングページを完全に省略し、/pay-invoice/ に直接移動します」
• 「browse type ではなく browse fill #field_3 value を使います。このフィールドはフォーカス時に内容が消去されます」
• 「ターン 8 でページにスピナーが表示されています。スナップショットの前に browse wait timeout 2000 を追加します」
• （--browser-trace を使用した場合）「unified-events.jsonl の 47 行目では、browse open の直後に /api/availability への Network.responseReceived イベントが 3 回連続で記録され、いずれも 403 を返しています — サイトがフィンガープリントで判別しています。次のイテレーションでは --verified --proxies が必要です。」

strategy.md を更新する

./autobrowse/tasks/<task-name>/strategy.md を編集します。うまくいった内容はすべて残し、具体的な失敗を修正して、実用的なヒューリスティックを追加します。

優れた戦略には、次の要素があります。

• 最短経路：探索を省略できる直接 URL またはショートカット
• 段階的なワークフロー：タイミングの注記を含む、正確な手順
• サイト固有の知識：セレクター ID、フォームフィールド名、成功を示す要素
• 失敗時の復旧方法：問題 X が起きたときに行うこと

結果を判定する

新しいサマリーを読みます。成功しましたか？ 明確な進展はありましたか？

• 成功または進展あり → 維持して、次のイテレーションへ
• 進展なし、または後退 → strategy.md を前のバージョンに戻し、別の仮説を試します

実行可能なスクリプトを生成する（任意）

タスクが収束したら、scripts/codegen.mjs を介して、1 つ以上のフレームワークで決定論的で実行可能なスクリプトを生成できます。これはフレームワークごとに 1 回の LLM 呼び出しで、コンテンツハッシュによってキャッシュされ、オプションで新しいセッションに対する検証と、失敗時の書き換えを行います。

node ${CLAUDE_SKILL_DIR}/scripts/codegen.mjs \
  --task <name> \
  --workspace ./autobrowse \
  --frameworks playwright,stagehand \
  --verify

各フレームワークは tasks/<name>/<framework>/ 配下に独自のサブディレクトリを持ち、出力されたスクリプトと自己完結型のスキャフォールド（package.json、tsconfig.json）が含まれます。このディレクトリは cd tasks/<name>/playwright && npm install && npx tsx <name>.ts で単体で実行可能です。唯一のランタイム要件は BROWSERBASE_API_KEY（Stagehand ターゲットの場合はさらに ANTHROPIC_API_KEY）です。

組み込みフレームワーク: playwright、stagehand。カスタムフレームワークを追加するには --prompt-template <path> --frameworks custom を使用します（独自のランナーを用意するか、--no-verify を渡してください）。

一般的なフラグ:

フラグ	目的
--frameworks a,b,...	カンマ区切り。デフォルトは playwright
--verify / --no-verify	生成されたスクリプトを新しい BB セッションに対して実行します。デフォルトは --verify
--max-retries N	検証失敗時の書き換え上限。デフォルトは 2
--cache-only	キャッシュミスの場合はエラー（CI 向け）
--force	キャッシュを無効化します
--dry-run	プロンプトのサイズとコストを見積もります。LLM は呼び出しません
--run <id>	特定の run-NNN を強制します（デフォルト: 最新の合格したもの）

出力はフレームワークごとに stdout に 1 行の JSON です。選択されたフレームワークのいずれかの最終状態が passed: false の場合、終了コードは非ゼロになります。

出力されるスクリプトが従う標準的な connectOverCDP パターンについては、references/playwright-cdp-bridge.md を参照してください。

すべてのイテレーションの後 — 準備ができていれば公開する

タスクが直近 3 回のイテレーションのうち 2 回以上で合格した場合、または最大イテレーション上限に達した場合、それを Claude Code スキルとしてインストールします。strategy.md をただコピーしないでください — スキルは自己完結型であり、このコードベースを見たことがない人にとっても有用でなければなりません。クリーンな合格なしに最大イテレーションで昇格する場合は、既知の失敗点を記録しつつ、学んだことをすべて文書化してください。

~/.claude/skills/<task-name>/SKILL.md に書き込むことでインストールします:

mkdir -p ~/.claude/skills/<task-name>

SKILL.md には次の構造を使用してください:

---
name: <task-name>
description: <1-2 sentences describing what this skill does and when to use it. Include trigger keywords.>
---

# <Task Title> — Browser Skill

## Purpose
<1-2 sentences: what this automates and why it exists.>

## When to Use
<When should someone reach for this skill.>

## Browse CLI Reference
The inner agent uses the `browse` CLI. Key commands for this task:
- `browse stop` — kill existing session (always run before switching to remote)
- `browse open <url> --remote` — start a fresh Browserbase cloud session and navigate
- `browse open <url> --local` — start a clean local browser and navigate
- `browse tab new <url>` — open URL in a new tab
- `browse wait load` — wait for page to finish loading
- `browse wait timeout <ms>` — wait a fixed amount of time for spinners or animations
- `browse wait selector "<selector>"` — wait for an element to become visible
- `browse get title` — verify you're on the right page
- `browse get text body` — extract all visible text (preferred for content extraction)
- `browse snapshot` — get accessibility tree; each node has a ref in `[X-Y]` format (e.g. `[0-5]`, `[2-147]`)
- `browse click [X-Y]` — click element by ref from the latest snapshot (include the brackets)

**Never use `--session <name>` flags in SKILL.md.** Named sessions are a parallel-run workaround — they contaminate skills with infrastructure concerns. Skills must work in isolation with the default session.

## Workflow

### Step 1 — Start session
<exact browse commands in order>

### Step 2 — Navigate
<exact URL and verification steps>

### Step 3 — Extract
<exact extraction commands>

### Step 4 — Output
<what JSON to emit, referencing the schema below>

## Site-Specific Gotchas
<Bullet list of every hard-won heuristic from the iterations. This is the core value of the skill.>

## Failure Recovery
<What to do when navigation fails, session is contaminated, or extraction returns garbage>

## Expected Output
```json
<paste the exact expected output schema from task.md>

After writing the SKILL.md, confirm it's installed:
```bash
ls ~/.claude/skills/<task-name>/SKILL.md

これでスキルは Claude Code で /<task-name> として利用可能になります。

---

最終レポート（マルチタスクモード）

すべてのサブエージェントが完了したら、markdown テーブルを出力します:

Task	Iterations	Final Status	Graduated	Cost
google-flights	5	✅ pass	yes	$0.42
amazon-add-to-cart	5	❌ fail	no	$1.20

次に、./autobrowse/reports/ に永続的なセッションレポートを書き込み、ワークスペース内にその実行の耐久性のある記録を残します:

mkdir -p ./autobrowse/reports

ファイル ./autobrowse/reports/YYYY-MM-DD-HH-MM-<tasks>.md を次の内容で書き込みます:

# AutoBrowse Session Report
**Date:** <ISO date>
**Tasks:** <comma-separated list>
**Environment:** remote|local
**Total cost:** $X.XX

## Results

| Task | Iterations | Pass Rate | Final Status | Graduated | Cost |
|------|-----------|-----------|--------------|-----------|------|
| ... | ... | X/5 | ✅/❌ | yes/no | $X.XX |

## Per-Task Learnings

### <task-name>
- **Key insight 1:** <what the agent learned>
- **Key insight 2:** <another heuristic>
- **Failure mode fixed:** <what was failing and how it was resolved>

## Iteration Log

### <task-name>
| Iter | Turns | Cost | Status | Hypothesis tested |
|------|-------|------|--------|-------------------|
| 1 | 79 | $18.75 | ❌ fail | baseline |
| 2 | 9 | $0.26 | ✅ pass | session contamination fix |
| ... | ... | ... | ... | ... |

---

ルール

• 編集するのは strategy.md のみ — task.md（テンプレートから作成する場合を除く）や evaluate.mjs には決して触れないでください
• ワークスペース内にとどまる — すべてのトレーニングの書き込みは ./autobrowse/ に行われ、~/.claude/skills/autobrowse/ には決して行いません。スキルのソースは読み取り専用です。
• 1 イテレーションにつき 1 つの仮説 — 一度に 1 つの変更をテストしてください
• 成功の上に築く — うまくいったことを維持し、そこに追加してください
• トレースを信頼する — 内部エージェントは、何を見て何をしたかを正確に示します
• ~/.claude/skills/ に昇格する — そこに書き込む唯一のファイルは、最終的に昇格した SKILL.md です
• バイセクトする前にリリースしない — --browser-trace では、各イテレーションの最後の順序は譲れません: stop-capture → bisect-cdp → browse cloud sessions update REQUEST_RELEASE。バイセクトは、トレースが停止したときにセッションがまだ存在していることに依存します。