SkillRepo
Sign InSign Up
Catalog
openai/screenshot

openai

screenshot

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.

global
0installs0uses—~1.9k
v1.0Saved Apr 5, 2026

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.
Files10
10 files · 43.2 KB

Select a file to preview

Overall Score

87/100

Grade

A

Excellent

Safety

88

Quality

87

Clarity

88

Completeness

84

Summary

Screenshot Capture is a cross-platform skill that guides agents to capture desktop screenshots using OS-native tools and bundled helper scripts. It supports full-screen, window, region, and app-specific captures on macOS, Linux, and Windows, with intelligent permission handling and flexible output path resolution.

Detected Capabilities

macOS screenshot capture with window-specific and display-aware selectionLinux screenshot capture with tool detection (scrot, gnome-screenshot, ImageMagick)Windows screenshot capture via PowerShellmacOS permission preflight for Screen Recording accessRegion and pixel-coordinate-based captureMulti-display handling with per-display file outputUser-specified or OS-default output path resolutionInteractive screenshot selection where supported

Trigger Keywords

Phrases that MCP clients use to match this skill to user intent.

capture screenshotscreenshot desktopscreenshot apptake screenshotscreenshot windowcapture regionscreenshot regioninspect uivisual check

Risk Signals

INFO

macOS permission escalation pattern

scripts/ensure_macos_permissions.sh:28-30, take_screenshot.py:369-377
INFO

Shell command execution via subprocess.run()

scripts/take_screenshot.py:multiple (capture_macos, capture_linux, run function)
INFO

Swift helper script execution

scripts/take_screenshot.py:198-209 (swift_json function), scripts/ensure_macos_permissions.sh:13-18
INFO

OSAScript execution for app activation

scripts/take_screenshot.py:261-265 (activate_app function)
INFO

File I/O to temp and user-specified directories

scripts/take_screenshot.py:140-162 (resolve_output_path), entire capture_* functions
INFO

Environment variable reads for test/override modes

scripts/take_screenshot.py:51-77 (TEST_MODE_ENV, TEST_PLATFORM_ENV, TEST_WINDOWS_ENV, TEST_DISPLAYS_ENV)

Referenced Domains

External domains referenced in skill content, detected by static analysis.

www.apache.org

Use Cases

  • Capture screenshots of running applications for visual inspection or debugging
  • Record UI state before and after code changes for visual regression testing
  • Gather screenshots of specific windows or screen regions for documentation or bug reports
  • Inspect Codex's own visual state during agent workflow execution

Quality Notes

  • Excellent structure with clear platform-specific sections (macOS, Linux, Windows) and comprehensive error handling for each platform's unique requirements.
  • Well-documented save-location precedence (user path → OS default → temp), reducing ambiguity for agents.
  • Python helper includes extensive argument validation (parse_region, argument conflicts checked with clear SystemExit messages) to prevent invalid combinations.
  • macOS permission preflight script explicitly handles sandbox context and guides users to System Settings when permission is denied — good UX.
  • Comprehensive coverage of OS-specific tools with fallback logic: Linux tries scrot → gnome-screenshot → ImageMagick in order of preference.
  • Multi-display support with intelligent suffix generation (-w<windowId>, -d<displayId>) makes output clear when multiple files are created.
  • Test mode infrastructure (TEST_MODE_ENV, test_mode_enabled()) allows for deterministic testing without real screenshots.
  • Bash helper (ensure_macos_permissions.sh) is minimal, single-purpose, and uses strict mode (set -euo pipefail).
  • PowerShell helper documented but not included in file manifest — users are directed to it but the implementation is not present here for review (reference only).
  • Edge cases handled: empty window list, missing tools on Linux, permission errors, module-cache sandbox issues on macOS.
  • Clear error messages guide agents toward resolution (e.g., 'no supported screenshot tool found (scrot, gnome-screenshot, or import)').
Model: claude-haiku-4-5-20251001Analyzed: Apr 5, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Add openai/screenshot to your library

Get Started Free

Command Palette

Search for a command to run...