The Screenshot skill gives Codex a reliable, cross-platform way to capture desktop screenshots without relying on browser-specific tooling. Whether Codex needs a quick visual check of a running application, you’ve asked for a screenshot of a specific window, or you need to compare a live UI against a Figma design, this skill selects the right OS-level capture method automatically and saves the result to the correct location. Bundled helper scripts handle platform differences so Codex never has to derive OS-specific commands from scratch.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/openai/skills/llms.txt
Use this file to discover all available pages before exploring further.
Installing
What This Skill Does
The Screenshot skill provides OS-level screenshot capture for:- Full-screen captures across all connected displays
- App and window captures by application name or window title (macOS)
- Pixel-region captures using
x,y,width,heightcoordinates - Active / frontmost window capture
- Specific window capture by window ID
Trigger Conditions
Codex activates this skill when:- The user explicitly asks for a desktop or system screenshot
- A full-screen, specific app or window, or pixel-region capture is requested
- Tool-specific capture (e.g., Figma MCP, Playwright) is unavailable and an OS-level capture is needed
- Codex needs a visual check of a running application for its own inspection
Prefer tool-specific screenshot capabilities when available — for example, use
the Figma skill for Figma designs or Playwright for browser/Electron apps. Use
this skill for native desktop apps and whole-system captures.
Platforms Supported
macOS
Full Python helper with app/window capture, display enumeration, and
permission preflight via Swift helpers.
Linux
Python helper with automatic tool selection:
scrot, gnome-screenshot,
or ImageMagick import.Windows
PowerShell helper with full-screen, region, and active-window capture.
macOS: Permission Preflight
Screen Recording permission is required on macOS for app and window captures. Run the bundled preflight script once before capturing to request the permission in a single place and avoid repeated sandbox prompts:macOS and Linux: Python Helper (take_screenshot.py)
Run the helper from the repo root. The script prints one file path per capture; when multiple windows or displays match it prints multiple paths (one per line) with suffixes like -w<windowId> or -d<display>.
Default location (user asked for “a screenshot”):
x,y,width,height):
--list-windows to discover IDs on macOS):
Linux Tool Selection
The helper automatically selects the first available tool in this order:scrotgnome-screenshot- ImageMagick
import
scrot or import. The --app, --window-name, and --list-windows flags are macOS-only; use --active-window or --window-id on Linux.
Windows: PowerShell Helper (take_screenshot.ps1)
Default location:
x,y,width,height):
Bundled Helper Scripts
| Script | Platform | Purpose |
|---|---|---|
take_screenshot.py | macOS, Linux | Primary Python capture helper |
take_screenshot.ps1 | Windows | PowerShell capture helper |
ensure_macos_permissions.sh | macOS | Screen Recording permission preflight |
macos_window_info.swift | macOS | Enumerate open windows and their IDs |
macos_display_info.swift | macOS | Enumerate connected displays |
macos_permissions.swift | macOS | Permission check implementation |
Multi-Display Behaviour
- macOS: full-screen captures save one file per display when multiple monitors are connected.
- Linux and Windows: full-screen captures use the virtual desktop (all monitors in one image). Use
--regionto isolate a single display.
Common Workflows
“Take a look at <App> and tell me what you see” — capture to temp, then view each path:Error Handling
- If macOS app/window capture returns no matches, run
--list-windows --app "AppName", then retry with--window-id. - If Linux region/window capture fails, verify tool availability with
command -v scrot,command -v gnome-screenshot, andcommand -v import. - If saving to the OS default location fails with permission errors in a sandbox, re-run with escalated permissions.
- Always confirm the saved file path in the response.