screenshot

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

スクリーンショットの保存先は、毎回次のルールに従ってください。

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

ツールの優先順位

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

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

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

ヘルパーは Swift のモジュールキャッシュを $TMPDIR/letta-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 "Letta Code"

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

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

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

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 "Letta Code"

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

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

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

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

• ピクセル領域（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> のような接尾辞を付けます。画像ビューアーツールで各パスを順番に表示し、必要な場合または依頼された場合にのみ画像を加工してください。

ワークフローの例

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

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

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

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 のデフォルトの保存場所への保存が権限エラーで失敗する場合は、昇格された権限でコマンドを再実行してください。
• 保存したファイルのパスは、必ず応答に記載してください。