openai-screenshot

スクリーンショットの撮影

毎回、次の保存先ルールに従ってください。

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

ツールの優先順位

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

macOS の権限確認（確認の繰り返しを減らす）

macOS では、ウィンドウやアプリをキャプチャする前に、事前確認用ヘルパーを一度実行してください。画面収録の権限を確認し、必要な理由を説明したうえで、一か所で権限をリクエストします。

ヘルパーは Swift のモジュールキャッシュを $TMPDIR/codex-swift-module-cache に設定し、追加のサンドボックスによるモジュールキャッシュの確認を避けます。

bash {baseDir}/scripts/ensure_macos_permissions.sh

サンドボックスの承認確認が何度も表示されないように、可能な場合は事前確認とキャプチャを1つのコマンドにまとめてください。

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "the agent"

エージェントによる確認では、出力先を一時ディレクトリにしてください。

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "<App>" --mode temp

OS ごとのコマンドをその都度調べ直さなくて済むよう、同梱のスクリプトを使用してください。

macOS と Linux（Python ヘルパー）

リポジトリのルートからヘルパーを実行してください。

python3 {baseDir}/scripts/take_screenshot.py

一般的な使用例：

• デフォルトの保存先（ユーザーが「スクリーンショットを撮って」と依頼した場合）：

python3 {baseDir}/scripts/take_screenshot.py

• 一時保存先（エージェントによる目視確認）：

python3 {baseDir}/scripts/take_screenshot.py --mode temp

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

python3 {baseDir}/scripts/take_screenshot.py --path output/screen.png

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

python3 {baseDir}/scripts/take_screenshot.py --app "the agent"

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

python3 {baseDir}/scripts/take_screenshot.py --app "the agent" --window-name "Settings"

• キャプチャ前に、一致するウィンドウ ID を一覧表示：

python3 {baseDir}/scripts/take_screenshot.py --list-windows --app "the agent"

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

python3 {baseDir}/scripts/take_screenshot.py --mode temp --region 100,200,800,600

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

python3 {baseDir}/scripts/take_screenshot.py --mode temp --active-window

• 特定のウィンドウ ID（macOS では --list-windows を使って ID を確認します）：

python3 {baseDir}/scripts/take_screenshot.py --window-id 12345

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

ワークフローの例

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

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/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 {baseDir}/scripts/take_screenshot.ps1

一般的な使用例：

• デフォルトの保存先：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1

• 一時保存先（エージェントによる目視確認）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp

• 明示的なパス：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"

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

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600

• アクティブなウィンドウ（まずユーザーにウィンドウへフォーカスするよう依頼してください）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow

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

powershell -ExecutionPolicy Bypass -File {baseDir}/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 {baseDir}/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 のデフォルトの保存先への保存時に権限エラーが発生した場合は、権限を昇格させてコマンドを再実行してください。
• 応答には必ず保存したファイルのパスを記載してください。

使用する場合

使用しない場合