Preface¶

When building or modifying frontend code and desktop applications with an Agent, developers often get stuck on the same problem: the code is finished, but they cannot see what the actual interface looks like. Browsers support page screenshots via Playwright, and Figma has dedicated design export capabilities; but once the target becomes a system-level window, a multi-monitor desktop, or a native application without an integrated screenshot API, the toolchain breaks.

The screenshot Agent Skill fills this gap. It instructs the Agent to take full-screen, windowed, or pixel-region screenshots using operating system capabilities, saves the results as image paths, and then hands them off to visual analysis tools for review one by one. This article is organized based on the original Skill documentation and installation instructions from the official OpenAI repository, explaining what it is, how to install and use it, and how to integrate it with Playwright and Figma.

What It Is¶

The screenshot is a set of reusable capability packages maintained by OpenAI in the .curated directory of the openai/skills repository. The directory includes the SKILL.md instruction file, cross-platform screenshot scripts (Python for macOS/Linux, PowerShell for Windows), plus macOS permission pre-check and window information helper scripts.

Its positioning is clear: when the user explicitly requests a desktop/system screenshot, or when dedicated tool screenshot capabilities cannot capture the target screen, use OS-level capture to supplement visual input. The Skill itself follows the universal Agent Skills format (SKILL.md + optional scripts/), so it can be used in AI coding tools that support this standard, such as Codex, Cursor, and Claude Code, after placing it in their respective skill directories.

Note: The repository README has marked that openai/skills is entering the deprecation and migration phase, and subsequent Codex skills and plugin examples will move to openai/plugins. If you still install from the curated list, you can continue using the $skill-installer method below; for long-term distribution, please refer to the official plugin documentation.

Core Features and Highlights¶

According to the official SKILL.md, its main capabilities can be summarized into the following categories.

1. Clear save location rules
   Save to the path specified by the user; if only “take a screenshot” is mentioned, save to the system’s default screenshot directory; when the Agent performs visual checks on its own, save to a temporary directory (--mode temp). The script outputs one or more lines of image paths each time, making it easy to open them sequentially with a image viewer.

2. Tool priority: dedicated tools first, then system tools
   Use Figma MCP/Skill first to capture design drafts; use Playwright / agent-browser first to capture browser or Electron pages. Only when the user explicitly requests a system screenshot, needs full desktop capture, or the dedicated tools cannot reach the target screen, enable this Skill. It serves as the default screenshot method only for desktop applications without better integration solutions.

3. Multi-platform, multi-granularity capture

   • Full screen
   • Pixel region (x,y,w,h)
   • Currently focused window
   • On macOS, you can also capture by application name, window title substring, or window ID, and support using --list-windows to list windows first before capturing
   • Multi-monitor: Full-screen capture on macOS will save one file per monitor; on Linux/Windows, full-screen capture is the entire virtual desktop image, use --region to crop for a single screen

4. macOS permission pre-check
   Before capturing windows or applications, you can run scripts/ensure_macos_permissions.sh first to centrally check and request Screen Recording permissions, reducing repeated pop-up prompts. The official recommends combining the pre-check and screenshot into a single command to reduce repeated authorization prompts in the sandbox.

5. Automatic tool selection for Linux
   The Python helper will try scrot → gnome-screenshot → ImageMagick import in order; if none are available, it will prompt the user to install them. Pixel region screenshot depends on scrot or import. The --app / --window-name / --list-windows flags are only available on macOS; on Linux, use --active-window or provide --window-id when available.

These capabilities together support visual QA workflows such as “design draft vs implementation”, “UI modification before and after comparison”, and “desktop application visual self-check”: Figma for design drafts, Playwright for web pages, and screenshot for desktop/native windows.

Installation and Activation¶

Install in Codex (Official Curated Method)¶

Curated skills can be installed by name using Codex’s built-in $skill-installer (pulled from skills/.curated by default):

$skill-installer screenshot

You can also directly provide the GitHub directory address:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/screenshot

If the skill does not appear in the skill list after installation, restart Codex as instructed in the official documentation and try again.

Manual Activation in Cursor / Claude Code and Other Tools¶

A Skill is essentially a folder. Place the screenshot directory into the skills path that the corresponding tool scans. The directory must at least contain SKILL.md, and retain auxiliary files such as scripts/.

Common paths (project-level / user-level):

Manual example (for Cursor project-level):

mkdir -p .cursor/skills
# Clone the repository and copy the curated directory, or sparse checkout the subdirectory
cp -R /path/to/openai/skills/skills/.curated/screenshot .cursor/skills/screenshot

Cursor will automatically detect the skill after startup; you can also search for screenshot with / in the Agent chat to manually call it. As long as the scripts/ directory remains, the Agent can execute the actual screenshot commands according to the path in SKILL.md.

Typical Usage Examples¶

All the following commands come from the official SKILL.md, replace <path-to-skill> with the local Skill root directory.

macOS / Linux: Python Helper¶

Take a default screenshot (saved to the system default location):

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

Use temporary directory for Agent self-check:

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

Specify output path:

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

Capture a window by application name (macOS only, supports substring matching, will output one file per matched window):

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

Filter by window title within the application, or list window IDs first:

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

Pixel region and currently focused window:

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

macOS recommended “permission pre-check + screenshot” one-time run:

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

Official workflow example: The user says “Help me check what’s on the interface” → take a screenshot to temp directory → open the printed paths one by one with an image viewer; the user says “There is a discrepancy between the Figma design and the implementation” → first use Figma-related capabilities to capture the design draft, then use this Skill to capture the running application, compare the original screenshots, and avoid unnecessary image processing first.

Windows: PowerShell Helper¶

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

Before using -ActiveWindow, the user needs to bring the target window to the foreground first.

Fallback System Commands When Helper Is Unavailable¶

The official also provides fallback写法 that directly call system commands, such as screencapture for macOS, scrot / gnome-screenshot / import for Linux. Prioritize using the bundled scripts when possible to avoid manually piecing together platform differences.

Applicable Scenarios and Notes¶

Suitable Scenarios¶

• Visual inspection and debugging of desktop/native applications
• Interface documentation and simple visual regression comparison before and after UI changes
• Locating a specific screen area in a multi-monitor environment
• Collaborating with Figma (design) and Playwright (browser/Electron) for “design → implementation → runtime” comparison

Usage Notes¶

• macOS requires resolving Screen Recording permissions; if screenshots are blocked, “unable to create image from display”, or Swift ModuleCache permission errors occur in the sandbox, you need to elevate permissions and rerun the command.
• If the application/window cannot be captured, first run --list-windows --app "AppName" to confirm the application is visible on the screen, then switch to using --window-id.
• If region/window capture fails on Linux, first check dependencies with command -v scrot, gnome-screenshot, and import.
• If saving to the system default screenshot directory fails due to sandbox permissions, you also need to elevate permissions and retry.
• Always report the save path in your response; when multiple windows or monitors are matched, multiple paths will be output with suffixes like -w / -d, and you need to review each one individually.
• Do not treat this Skill as the first choice for browser screenshots: prioritize dedicated tools such as Playwright for web scenarios.

Summary¶

The screenshot Skill packages “operating system-level screenshot” into a discoverable and executable Skill for Agents: unified save strategy, cross-platform helper scripts, clear tool priority, and a visual QA workflow that connects with Figma and Playwright. After installation, the Agent no longer has to only “guess the interface”, but can actually take photos of the desktop screen for analysis.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/screenshot
Original Skill documentation (SKILL.md): https://raw.githubusercontent.com/openai/skills/main/skills/.curated/screenshot/SKILL.md
Codex Skills Documentation: https://developers.openai.com/codex/skills
Cursor Skills Documentation: https://cursor.com/docs/skills
Agent Skills Open Standard: https://agentskills.io