chrome-devtools

Chrome DevTools Agent Skill

実行可能な Puppeteer スクリプトを使ったブラウザー自動化。すべてのスクリプトは、解析しやすいように JSON を出力します。

クイックスタート

重要：スクリプトを実行する前に、必ず pwd を確認してください。

インストール

ステップ 1：システム依存関係のインストール（Linux/WSL のみ）

Linux/WSL では、Chrome にシステムライブラリが必要です。最初にインストールしてください。

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

対応環境：Ubuntu、Debian、Fedora、RHEL、CentOS、Arch、Manjaro

macOS/Windows：このステップはスキップしてください（依存関係は Chrome に含まれています）

ステップ 2：Node の依存関係のインストール

# Preferred: Using bun (faster)
bun install  # Installs puppeteer, debug, yargs

# Alternative: Using npm
npm install

ステップ 3：ImageMagick のインストール（任意、推奨）

ImageMagick を使うと、スクリーンショットを自動圧縮し、ファイルサイズを 5MB 未満にできます。

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

確認：

magick -version  # or: convert -version

ImageMagick がない場合、5MB を超えるスクリーンショットは圧縮されません（Gemini/Claude で読み込めない可能性があります）。

テスト

bun navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

利用可能なスクリプト

すべてのスクリプトは .claude/skills/chrome-devtools/scripts/ にあります。

重要：スクリプトを実行する前に、必ず pwd を確認してください。

スクリプトの使い方

• ./scripts/README.md

コア自動化

• navigate.js - URL に移動
• screenshot.js - スクリーンショットを撮影（ページ全体または要素）
• click.js - 要素をクリック
• fill.js - フォームフィールドに入力
• evaluate.js - ページのコンテキストで JavaScript を実行

分析とモニタリング

• snapshot.js - メタデータ付きでインタラクティブ要素を抽出
• console.js - コンソールのメッセージとエラーを監視
• network.js - HTTP リクエストとレスポンスを追跡
• performance.js - Core Web Vitals を測定し、トレースを記録

使用パターン

単一コマンド

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png

重要：スクリーンショットは必ず ./docs/screenshots ディレクトリに保存してください。

画像の自動圧縮

スクリーンショットが 5MB を超える場合、Gemini API および Claude Code（上限は 5MB）との互換性を確保するため、自動的に圧縮されます。この処理では内部で ImageMagick を使用します。

# Default: auto-compress if >5MB
bun screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
bun screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
bun screenshot.js --url https://example.com --output page.png --no-compress

圧縮の動作：

• PNG：サイズを 90% に変更し、品質を 85 に設定（それでも大きすぎる場合は 75% に変更し、品質を 70 に設定）
• JPEG：品質を 80 に設定し、プログレッシブエンコードを適用（それでも大きすぎる場合は品質を 60 に設定）
• その他の形式：圧縮して JPEG に変換
• ImageMagick のインストールが必要です（imagemagick スキルを参照）

出力には圧縮情報が含まれます：

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

コマンドの連結（ブラウザーを再利用）

# Keep browser open with --close false
bun navigate.js --url https://example.com/login --close false
bun fill.js --selector "#email" --value "[email protected]" --close false
bun fill.js --selector "#password" --value "secret" --close false
bun click.js --selector "button[type=submit]"

JSON 出力の解析

# Extract specific fields with jq
bun performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
bun network.js --url https://example.com --output /tmp/requests.json

実行プロトコル

作業ディレクトリの確認

スクリプトを実行する前に、次の手順を行ってください。

1. pwd で現在の作業ディレクトリを確認します
2. .claude/skills/chrome-devtools/scripts/ ディレクトリにいることを確認します
3. 正しいディレクトリにいない場合は、正しい場所に cd します
4. すべての出力ファイルには絶対パスを使用します

例：

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

出力の検証

スクリーンショットの撮影／キャプチャ後に、次の手順を行ってください。

1. ls -lh <output-path> でファイルが作成されたことを確認します
2. Read ツールでスクリーンショットを読み込み、内容を確認します
3. JSON 出力で success:true を確認します
4. ファイルサイズと圧縮状態を報告します

例：

bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

5. 作業ディレクトリをプロジェクトのルートに戻します。

エラーからの復旧

スクリプトが失敗した場合：

1. エラーメッセージでセレクターの問題を確認します
2. snapshot.js を使って正しいセレクターを見つけます
3. CSS セレクターが失敗する場合は、XPath セレクターを試します
4. 要素が表示され、操作可能であることを確認します

例：

# CSS selector fails
bun click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
bun snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# Try XPath
bun click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

共通オプション

すべてのスクリプトで次のオプションを使用できます。

• --headless false - ブラウザーウィンドウを表示します（デフォルト：true）
• --close false - スクリプトの実行後もブラウザーを開いたままにします
• --timeout 30000 - タイムアウト時間（ミリ秒、デフォルト：30000）
• --help - スクリプト固有のヘルプを表示します

トラブルシューティング

ブラウザーを起動できない（Linux）：

./install-deps.sh  # Install missing system libraries

スクリーンショットのファイルサイズが大きい場合：

• ImageMagick を有効にして自動圧縮を使用します
• --max-size を使ってしきい値を指定します
• または、ページ全体ではなく特定の要素をキャプチャします

要素が見つからない場合：

• 最初に snapshot.js を使ってセレクターを見つけます
• 要素が動的に読み込まれているか確認します（さらに待ちます）
• CSS で失敗する場合は XPath を試します

スクリプトが見つからない場合：

• 正しいディレクトリにいることを確認します
• スクリプト名のスペルを確認します
• 絶対パスを使用します：bun /path/to/scripts/navigate.js