Use screenshot to document a desktop app’s error state, illustrate an interface or let Codex inspect visible layout. Specify a full screen, foreground window or pixel region. The workflow captures an accessible desktop and should deliver a real image with its saved path; a written description alone does not establish successful capture.
Install and prepare
This guide covers the standalone Skill retained in openai/skills. That repository is deprecated and current examples have moved to openai/plugins; the instructions here describe the linked standalone version, not the latest plugin.
Enter this line in the Codex conversation, not a terminal. If the installed Skill does not appear, restart Codex.
$skill-installer screenshot
- A local graphical desktop accessible to the Codex runtime
- An open target app with the relevant content visible
- Python 3 for the macOS/Linux helper, or PowerShell on Windows
- Screen recording permission on macOS; scrot, gnome-screenshot or ImageMagick import on Linux
On macOS, check the capturing app under System Settings → Privacy & Security → Screen & System Audio Recording if permission is missing. Labels may vary by macOS version. The user manages this system permission; the Skill cannot bypass it. [4]
Try a first task
Bring the target window to the foreground, then request a capture:
$screenshot
Capture the application window I have placed in the foreground and save it to output/screenshots/current-window.png. Check the operating system and capture method first; avoid accidentally capturing the whole desktop. Open the saved image, verify its title and contents, and return its path. If no desktop session is accessible, permissions are missing or the window is unavailable, explain the blocker instead of claiming success.
Work through the task
-
Specify target and destination. Choose full screen, foreground window or an x, y, width, height region. A supplied path takes priority; otherwise a requested screenshot uses the OS default location, while Codex’s own inspection uses a temporary directory.
-
Respect platform differences. App-name, window-title and window-list selection are macOS-only in this version. An app match can return several windows. Linux needs its supported window controls; Windows uses the PowerShell helper and requires the intended active window to be foregrounded.
-
Inspect every returned image. Verify target, bounds and readable content. macOS can create a separate file per display. Linux and Windows full-screen captures use the combined virtual desktop; specify a region to isolate a display.
Choose the right capture target first
For a browser page or Figma file, prefer that tool’s own screenshot feature when available. This Skill is useful for an entire desktop, native-app window or explicit pixel region. State the display, window and destination in the request. For example: “Capture the active app window to artifacts/settings-before.png; show me the result before sharing it so adjacent displays and private notifications are excluded.”
macOS may ask for Screen Recording permission on first use. If the image is still black after approval, verify that the running Codex process has the permission and retry. App-name matching can find several windows; list them and choose a window ID when precision matters. Linux needs a graphical session and a supported screenshot utility; macOS window-name options do not transfer directly.
Inspect the image, not just its filename
Open every returned image and check that the target is visible, not hidden by a dialog, text is legible, and the crop matches the request. A whole-screen capture on multiple macOS displays may produce more than one file; identify each deliverable. A screenshot records one moment. If the goal is to verify that a button works, interaction and resulting state still need separate inspection.
Check the result
Expect actual image files and resolvable paths. Check for the wrong window, clipped text or unintended displays. Inspect each file when several are returned. For design comparisons, preserve original captures before adding crops or annotations.
Common blockers
macOS finds no matching window. Make the app visible, list matching windows and retry with an explicit window ID.
Linux region capture fails. Check installed capture tools. The helper requires scrot or ImageMagick import for regions; gnome-screenshot alone is insufficient.
The image is blank or no desktop exists. Report missing permissions or desktop access, restore those conditions and retry. A filename does not prove useful capture.
A browser or Figma capture is incomplete. Prefer its dedicated capture tool where available. A desktop screenshot does not automatically capture a full scrolling page.
Test capture with a nonsensitive window
On a new machine, first capture a window without private information, open the file, and check the target, clarity, and destination. Before capturing a real failure, hide notifications, tokens, and customer data; use a region or named window when sharing. An independent static review notes limited public execution evidence across platforms, so a returned filename alone should not be treated as a verified capture.