screenshot

スクリーンショット取得

保存先については、毎回以下のルールに従ってください。

1. ユーザーがパスを指定した場合は、そのパスに保存します。
2. ユーザーがパスを指定せずにスクリーンショットを求めた場合は、OS のデフォルトのスクリーンショット保存先に保存します。
3. Codex 自身が確認のためにスクリーンショットを必要とする場合は、一時ディレクトリに保存します。

ツールの優先順位

• 利用可能な場合は、ツール固有のスクリーンショット機能を優先してください（例: Figma ファイルには Figma MCP/スキル、ブラウザや Electron アプリには Playwright/agent-browser ツール）。
• このスキルは、明示的に依頼された場合、デスクトップ全体のキャプチャが必要な場合、またはツール固有のキャプチャで必要なものが取得できない場合に使用してください。
• それ以外の場合は、より適切に統合されたキャプチャツールがないデスクトップアプリに対して、このスキルをデフォルトとして扱ってください。

macOS の権限事前確認（繰り返し表示されるプロンプトを減らす）

macOS では、ウィンドウやアプリのキャプチャを行う前に、事前確認ヘルパーを一度実行してください。このヘルパーは画面収録の権限を確認し、必要な理由を説明して、一箇所でまとめて権限を要求します。

ヘルパーは、余分なサンドボックスのモジュールキャッシュプロンプトを避けるため、Swift のモジュールキャッシュを $TMPDIR/codex-swift-module-cache に向けます。

bash <path-to-skill>/scripts/ensure_macos_permissions.sh

サンドボックスの承認プロンプトが複数表示されるのを避けるため、可能であれば事前確認とキャプチャを 1 つのコマンドにまとめてください。

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"

Codex が確認のために実行する場合は、出力を一時ディレクトリに保存してください。

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp

OS ごとのコマンドを毎回導き出し直さないよう、同梱のスクリプトを使用してください。

macOS および Linux（Python ヘルパー）

リポジトリのルートからヘルパーを実行します。

python3 <path-to-skill>/scripts/take_screenshot.py

よく使うパターン:

• デフォルトの保存先（ユーザーが「スクリーンショット」を求めた場合）:

python3 <path-to-skill>/scripts/take_screenshot.py

• 一時ディレクトリ（Codex による視覚的確認）:

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp

• 明示的な保存先（ユーザーがパスまたはファイル名を指定した場合）:

python3 <path-to-skill>/scripts/take_screenshot.py --path output/screen.png

• アプリ名によるアプリ/ウィンドウのキャプチャ（macOS のみ。部分一致可。一致するすべてのウィンドウをキャプチャします）:

python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"

• アプリ内の特定のウィンドウタイトル（macOS のみ）:

python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --window-name "Settings"

• キャプチャ前に一致するウィンドウ ID を一覧表示（macOS のみ）:

python3 <path-to-skill>/scripts/take_screenshot.py --list-windows --app "Codex"

• ピクセル領域（x,y,w,h）:

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --region 100,200,800,600

• フォーカスされている/アクティブなウィンドウ（最前面のウィンドウのみをキャプチャします。すべてのウィンドウをキャプチャするには --app を使用してください）:

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --active-window

• 特定のウィンドウ ID（macOS では --list-windows で ID を確認してください）:

python3 <path-to-skill>/scripts/take_screenshot.py --window-id 12345

スクリプトは、キャプチャごとに 1 つのパスを出力します。複数のウィンドウやディスプレイが一致する場合は、複数のパスを（1 行に 1 つずつ）出力し、-w<windowId> や -d<display> のようなサフィックスを付けます。画像ビューアツールで各パスを順番に表示し、画像の加工は必要な場合または依頼された場合にのみ行ってください。

ワークフローの例

• 「 を見て、何が表示されているか教えて」: 一時ディレクトリにキャプチャし、出力されたパスを順番に 1 つずつ表示します。

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp

• 「Figma のデザインと実装が一致していない」: まず Figma MCP/スキルでデザインをキャプチャし、次にこのスキルで実行中のアプリをキャプチャします（通常は一時ディレクトリに保存）。加工する前に、生のスクリーンショット同士を比較してください。

マルチディスプレイの動作

• macOS では、複数のモニターが接続されている場合、全画面キャプチャはディスプレイごとに 1 つのファイルを保存します。
• Linux および Windows では、全画面キャプチャは仮想デスクトップ（すべてのモニターを 1 つの画像にまとめたもの）を使用します。必要に応じて --region を使用して、単一のディスプレイを切り出してください。

Linux の前提条件と選択ロジック

ヘルパーは、利用可能な最初のツールを自動的に選択します。

1. scrot
2. gnome-screenshot
3. ImageMagick の import

いずれも利用できない場合は、ユーザーにいずれかのインストールを依頼し、再試行してください。

座標による領域指定には scrot または ImageMagick の import が必要です。

--app、--window-name、--list-windows は macOS 専用です。Linux では、--active-window を使用するか、利用可能な場合は --window-id を指定してください。

Windows（PowerShell ヘルパー）

PowerShell ヘルパーを実行します。

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1

よく使うパターン:

• デフォルトの保存先:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1

• 一時ディレクトリ（Codex による視覚的確認）:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp

• 明示的なパス:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"

• ピクセル領域（x,y,w,h）:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600

• アクティブなウィンドウ（先にユーザーにフォーカスしてもらうよう依頼してください）:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow

• 特定のウィンドウハンドル（指定された場合のみ）:

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -WindowHandle 123456

OS のコマンドを直接使用する方法（フォールバック）

ヘルパーを実行できない場合にこれらを使用してください。

macOS

• 特定のパスへの全画面キャプチャ:

screencapture -x output/screen.png

• ピクセル領域:

screencapture -x -R100,200,800,600 output/region.png

• 特定のウィンドウID:

screencapture -x -l12345 output/window.png

• 対話的な選択またはウィンドウの選択:

screencapture -x -i output/interactive.png

Linux

• 全画面:

scrot output/screen.png

gnome-screenshot -f output/screen.png

import -window root output/screen.png

• ピクセル領域:

scrot -a 100,200,800,600 output/region.png

import -window root -crop 800x600+100+200 output/region.png

• アクティブなウィンドウ:

scrot -u output/window.png

gnome-screenshot -w -f output/window.png

エラー処理

• macOS では、まず bash <path-to-skill>/scripts/ensure_macos_permissions.sh を実行して、画面収録の権限を一括で要求してください。
• サンドボックス内での実行時に「screen capture checks are blocked in the sandbox」「could not create image from display」、または Swift の ModuleCache の権限エラーが表示された場合は、昇格された権限でコマンドを再実行してください。
• macOS のアプリ/ウィンドウキャプチャで一致する結果が返されない場合は、--list-windows --app "AppName" を実行し、--window-id を指定して再試行してください。また、対象のアプリが画面上に表示されていることを確認してください。
• Linux の領域/ウィンドウキャプチャが失敗する場合は、command -v scrot、command -v gnome-screenshot、command -v import を使ってツールが利用可能か確認してください。
• サンドボックス内で OS のデフォルトの保存場所への保存が権限エラーで失敗する場合は、昇格された権限でコマンドを再実行してください。
• 保存したファイルのパスは、必ず応答に記載してください。