screenshot

name	screenshot
name_en	Screenshot
name_zh-CN	屏幕截图
name_zh-TW	螢幕截圖
name_ja	スクリーンショット
name_ko	스크린샷
name_vi	Chụp màn hình
name_ru	Скриншот
name_pt	Captura de tela
name_es	Captura de pantalla
name_fr	Capture d'écran
name_de	Bildschirmfoto
description	Use when the user explicitly asks for a desktop or system screenshot (full screen, specific app or window, or a pixel region), or when tool-specific capture capabilities are unavailable and an OS-level capture is needed.
description_zh-CN	用户明确要求截屏(整屏、指定应用/窗口、或某块像素区域)时使用。当当前工具自带的捕获能力缺失、需要 OS 级别截图时也调用本技能。
description_zh-TW	使用者明確要求截圖(整螢幕、指定應用程式/視窗、或某塊像素區域)時使用。當前工具內建的截圖能力缺失、需要 OS 級截圖時也呼叫本技能。
description_ja	ユーザーがデスクトップやシステムのスクリーンショット(全画面、特定のアプリやウィンドウ、ピクセル領域)を明示的に求めるとき、または現在のツール固有のキャプチャ機能が使えず OS レベルのキャプチャが必要なときに使用します。
description_ko	사용자가 데스크톱이나 시스템 스크린샷(전체 화면, 특정 앱이나 창, 또는 픽셀 영역)을 명시적으로 요청하거나, 현재 도구의 캡처 기능을 사용할 수 없어 OS 수준의 캡처가 필요할 때 사용합니다.
description_vi	Sử dụng khi người dùng yêu cầu rõ ràng chụp màn hình desktop hoặc hệ thống (toàn màn hình, một ứng dụng/cửa sổ cụ thể, hoặc một vùng pixel), hoặc khi khả năng chụp riêng của công cụ không khả dụng và cần chụp ở mức OS.
description_ru	Использовать, когда пользователь явно просит снимок экрана рабочего стола или системы (весь экран, конкретное приложение или окно, либо область в пикселях), либо когда специфические возможности захвата текущего инструмента недоступны и требуется захват на уровне ОС.
description_pt	Use quando o usuário pedir explicitamente uma captura de tela do desktop ou do sistema (tela cheia, um aplicativo ou janela específica, ou uma região em pixels), ou quando os recursos de captura específicos da ferramenta não estiverem disponíveis e for necessária uma captura em nível de SO.
description_es	Úsalo cuando el usuario pida explícitamente una captura del escritorio o del sistema (pantalla completa, una app o ventana concreta, o una región en píxeles), o cuando las capacidades de captura propias de la herramienta no estén disponibles y se necesite una captura a nivel del SO.
description_fr	À utiliser quand l'utilisateur demande explicitement une capture d'écran du bureau ou du système (plein écran, une application/fenêtre spécifique, ou une zone en pixels), ou quand les capacités de capture propres à l'outil ne sont pas disponibles et qu'une capture au niveau de l'OS est nécessaire.
description_de	Verwenden, wenn der Nutzer explizit einen Screenshot des Desktops oder Systems anfragt (Vollbild, eine bestimmte App oder ein Fenster, oder einen Pixelbereich) oder wenn die toolspezifischen Aufnahmefunktionen fehlen und eine Aufnahme auf OS-Ebene benötigt wird.

Screenshot Capture

Follow these save-location rules every time:

1. If the user specifies a path, save there.
2. If the user asks for a screenshot without a path, save to the OS default screenshot location.
3. If Codex needs a screenshot for its own inspection, save to the temp directory.

Tool priority

• Prefer tool-specific screenshot capabilities when available (for example: a Figma MCP/skill for Figma files, or Playwright/agent-browser tools for browsers and Electron apps).
• Use this skill when explicitly asked, for whole-system desktop captures, or when a tool-specific capture cannot get what you need.
• Otherwise, treat this skill as the default for desktop apps without a better-integrated capture tool.

macOS permission preflight (reduce repeated prompts)

On macOS, run the preflight helper once before window/app capture. It checks Screen Recording permission, explains why it is needed, and requests it in one place.

The helpers route Swift's module cache to $TMPDIR/codex-swift-module-cache to avoid extra sandbox module-cache prompts.

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

To avoid multiple sandbox approval prompts, combine preflight + capture in one command when possible:

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

For Codex inspection runs, keep the output in temp:

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

Use the bundled scripts to avoid re-deriving OS-specific commands.

macOS and Linux (Python helper)

Run the helper from the repo root:

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

Common patterns:

• Default location (user asked for "a screenshot"):

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

• Temp location (Codex visual check):

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

• Explicit location (user provided a path or filename):

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

• App/window capture by app name (macOS only; substring match is OK; captures all matching windows):

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

• Specific window title within an app (macOS only):

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

• List matching window ids before capturing (macOS only):

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

• Pixel region (x,y,w,h):

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

• Focused/active window (captures only the frontmost window; use --app to capture all windows):

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

• Specific window id (use --list-windows on macOS to discover ids):

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

The script prints one path per capture. When multiple windows or displays match, it prints multiple paths (one per line) and adds suffixes like -w<windowId> or -d<display>. View each path sequentially with the image viewer tool, and only manipulate images if needed or requested.

Workflow examples

• "Take a look at and tell me what you see": capture to temp, then view each printed path in order.

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

• "The design from Figma is not matching what is implemented": use a Figma MCP/skill to capture the design first, then capture the running app with this skill (typically to temp) and compare the raw screenshots before any manipulation.

Multi-display behavior

• On macOS, full-screen captures save one file per display when multiple monitors are connected.
• On Linux and Windows, full-screen captures use the virtual desktop (all monitors in one image); use --region to isolate a single display when needed.

Linux prerequisites and selection logic

The helper automatically selects the first available tool:

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

If none are available, ask the user to install one of them and retry.

Coordinate regions require scrot or ImageMagick import.

--app, --window-name, and --list-windows are macOS-only. On Linux, use --active-window or provide --window-id when available.

Windows (PowerShell helper)

Run the PowerShell helper:

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

Common patterns:

• Default location:

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

• Temp location (Codex visual check):

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

• Explicit path:

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

• Pixel region (x,y,w,h):

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

• Active window (ask the user to focus it first):

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

• Specific window handle (only when provided):

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

Direct OS commands (fallbacks)

Use these when you cannot run the helpers.

macOS

• Full screen to a specific path:

screencapture -x output/screen.png

• Pixel region:

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

• Specific window id:

screencapture -x -l12345 output/window.png

• Interactive selection or window pick:

screencapture -x -i output/interactive.png

Linux

• Full screen:

scrot output/screen.png

gnome-screenshot -f output/screen.png

import -window root output/screen.png

• Pixel region:

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

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

• Active window:

scrot -u output/window.png

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

Error handling

• On macOS, run bash <path-to-skill>/scripts/ensure_macos_permissions.sh first to request Screen Recording in one place.
• If you see "screen capture checks are blocked in the sandbox", "could not create image from display", or Swift ModuleCache permission errors in a sandboxed run, rerun the command with escalated permissions.
• If macOS app/window capture returns no matches, run --list-windows --app "AppName" and retry with --window-id, and make sure the app is visible on screen.
• If Linux region/window capture fails, check tool availability with command -v scrot, command -v gnome-screenshot, and command -v import.
• If saving to the OS default location fails with permission errors in a sandbox, rerun the command with escalated permissions.
• Always report the saved file path in the response.