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 依存関係のインストール

npm install  # Installs puppeteer, debug, yargs

ステップ 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 で読み込めない可能性があります)。

テスト

node 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
node screenshot.js --url https://example.com --output ./docs/screenshots/page.png

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

自動画像圧縮

スクリーンショットが 5MB を超える場合、Gemini API と Claude Code (どちらも 5MB の制限があります) との互換性を確保するために、自動的に圧縮されます。内部では ImageMagick を使用しています:

# デフォルト: 5MB を超える場合は自動圧縮
node screenshot.js --url https://example.com --output page.png

# カスタムサイズ閾値 (例: 3MB)
node screenshot.js --url https://example.com --output page.png --max-size 3

# 圧縮を無効化
node 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
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "user@example.com" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

JSON 出力をパース

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

# Save to file
node 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. ファイルサイズと圧縮ステータスをレポート

例:

node 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
node click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

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

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

よくある間違い

❌ 作業ディレクトリが間違っている → 出力ファイルが間違った場所に行く ❌ 出力検証をスキップ → 静かに失敗する ❌ テストせずに複雑な CSS セレクタを使用 → セレクタエラー ❌ 要素の表示可能性を確認しない → タイムアウトエラー

✅ スクリプト実行前に必ず pwd を確認 ✅ スクリーンショット後に必ず出力を検証 ✅ snapshot.js を使用してセレクタを発見 ✅ シンプルなコマンドでセレクタをテスト

一般的なワークフロー

Web スクレイピング

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

パフォーマンステスト

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

フォーム自動化

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

エラーモニタリング

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

スクリプトオプション

すべてのスクリプトが対応:

• --headless false - ブラウザウィンドウを表示
• --close false - ブラウザを開いたままチェーニング用に保つ
• --timeout 30000 - タイムアウトを設定 (ミリ秒)
• --wait-until networkidle2 - 待機戦略

完全なオプションについては ./scripts/README.md を参照してください。

出力形式

すべてのスクリプトは JSON を stdout に出力します:

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

エラーは stderr に出力されます:

{
  "success": false,
  "error": "Error message"
}

要素を探す

snapshot.js を使用してセレクタを発見:

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

トラブルシューティング

よくあるエラー

"Cannot find package 'puppeteer'"

• 実行: スクリプトディレクトリで npm install

"error while loading shared libraries: libnss3.so" (Linux/WSL)

• システム依存関係が不足しています
• 修正: スクリプトディレクトリで ./install-deps.sh を実行
• 手動インストール: sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

"Failed to launch the browser process"

• システム依存関係がインストールされているか確認 (Linux/WSL)
• Chrome がダウンロードされたか確認: ls ~/.cache/puppeteer
• 試す: npm rebuild その後 npm install

Chrome が見つからない

• Puppeteer は npm install 中に Chrome を自動ダウンロードします
• 失敗した場合、手動でトリガー: npx puppeteer browsers install chrome

スクリプトの問題

要素が見つからない

• 最初にスナップショットを取得して正しいセレクタを探す: node snapshot.js --url <url>

スクリプトがハング

• タイムアウトを増やす: --timeout 60000
• 待機戦略を変更: --wait-until load または --wait-until domcontentloaded

スクリーンショットが空白

• ページロードを待つ: --wait-until networkidle2
• タイムアウトを増やす: --timeout 30000

スクリプトの実行権限が拒否

• 実行可能にする: chmod +x *.sh

スクリーンショットが大きすぎる (>5MB)

• 自動圧縮用に ImageMagick をインストール
• 手動で低い閾値を設定: --max-size 3
• PNG の代わりに JPEG フォーマットを使用: --format jpeg --quality 80
• フルページではなく特定の要素をキャプチャ: --selector .main-content

圧縮が機能しない

• ImageMagick がインストールされているか確認: magick -version または convert -version
• ファイルが実際に圧縮されたか出力 JSON で確認: "compressed": true
• 非常に大きなページの場合、--selector を使用して必要な領域のみをキャプチャ

リファレンスドキュメント

./references/ に詳細ガイドが利用可能:

• CDP Domains Reference - 47 の Chrome DevTools Protocol ドメイン
• Puppeteer Quick Reference - 完全な Puppeteer API パターン
• Performance Analysis Guide - Core Web Vitals の最適化

高度な使用法

カスタムスクリプト

共有ライブラリを使用してカスタムスクリプトを作成:

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

直接 CDP アクセス

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

詳細なパターンと完全な API カバレッジについてはリファレンスドキュメントを参照してください。

外部リソース

• Puppeteer Documentation
• Chrome DevTools Protocol
• Scripts README