openai-screenshot — Claude Code skill: what it does, how to install
openai-screenshot captures desktop screenshots, active windows, or pixel regions directly from Claude Code. Built for OS-level interface inspection.
Apache-2.0 ★ 540 updated 2026-07-14
/plugin marketplace add trailofbits/skills-curated
/plugin install openai-screenshot@skills-curatedWhat openai-screenshot does
The skill provides platform-specific scripts to capture screens on macOS, Linux, and Windows. It handles saving files to explicit paths, system default screenshot locations, or temporary directories when the agent needs visual feedback. On macOS, the helper captures windows by app name or title, saving individual files per display on multi-monitor setups.
Under the hood, it executes take_screenshot.py on Unix systems and take_screenshot.ps1 on Windows. When helper scripts fail to execute, the agent falls back to direct commands like screencapture or Linux tools including scrot, gnome-screenshot, and ImageMagick import.
On macOS, window and desktop capture fails until you grant Screen Recording permissions via the bundled preflight script.
What it helps with
- capture the full desktop across single or multiple monitors
- isolate an application window by process name on macOS
- crop a specific pixel region using exact coordinates
- store raw interface captures in a temporary folder for agent inspection
Example prompts for the agent
- Take a screenshot of the active window and store it in temp
- Capture the Settings window and save to output/screen.png
- Take a screenshot of region 100,200,800,600 to check the layout
How to install openai-screenshot
1Plugin marketplace
/plugin marketplace add trailofbits/skills-curated/plugin install openai-screenshot@skills-curatedThis installs the whole openai-screenshot plugin with all its skills
2Skills CLI (Vercel)
npx skills add trailofbits/skills-curated --skill openai-screenshot -a claude-code3Manually: put the files in place
~/.claude/skills/openai-screenshot/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openai-screenshot/
1Skills CLI (Vercel)
npx skills add trailofbits/skills-curated --skill openai-screenshot -a codex2Manually: put the files in place
.agents/skills/openai-screenshot/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add trailofbits/skills-curated --skill openai-screenshot -a cursor2Manually: put the files in place
.cursor/skills/openai-screenshot/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install trailofbits/skills-curated plugins/openai-screenshot/skills/openai-screenshot2Manually: put the files in place
.github/skills/openai-screenshot/SKILL.md1Skills CLI (Vercel)
npx skills add trailofbits/skills-curated --skill openai-screenshot -a gemini-cli2Platform CLI
gemini skills install https://github.com/trailofbits/skills-curated --path plugins/openai-screenshot/skills/openai-screenshotManually: put the files in place
.devin/skills/openai-screenshot/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about openai-screenshot
How to install openai-screenshot in Claude Code?
Add the repository and install the skill using these two commands in order: /plugin marketplace add trailofbits/skills-curated and /plugin install openai-screenshot@skills-curated.
What does openai-screenshot do?
It provides ready-made scripts and fallback commands that let Claude Code take screenshots of full screens, targeted app windows, or coordinate-based screen regions.
What are the requirements on Linux?
The helper searches for scrot, gnome-screenshot, or ImageMagick import. Coordinate region captures strictly require scrot or import.
Source text
SKILL.md · Apache-2.0
---
name: openai-screenshot
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. Originally from OpenAI's curated skills catalog.
allowed-tools:
- Bash
- Read
- Grep
- Glob
- Write
- Edit
---
# 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 the agent 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
bash {baseDir}/scripts/ensure_macos_permissions.sh
```
To avoid multiple sandbox approval prompts, combine preflight + capture in one
command when possible:
```bash
bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "the agent"
```
For the agent inspection runs, keep the output in temp:
```bash
bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/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:
```bash
python3 {baseDir}/scripts/take_screenshot.py
```
Common patterns:
- Default location (user asked for "a screenshot"):
```bash
python3 {baseDir}/scripts/take_screenshot.py
```
- Temp location (the agent visual check):
```bash
python3 {baseDir}/scripts/take_screenshot.py --mode temp
```
- Explicit location (user provided a path or filename):
```bash
python3 {baseDir}/scripts/take_screenshot.py --path output/screen.png
```
- App/window capture by app name (macOS only; substring match is OK; captures all matching windows):
```bash
python3 {baseDir}/scripts/take_screenshot.py --app "the agent"
```
- Specific window title within an app (macOS only):
```bash
python3 {baseDir}/scripts/take_screenshot.py --app "the agent" --window-name "Settings"
```
- List matching window ids before capturing (macOS only):
```bash
python3 {baseDir}/scripts/take_screenshot.py --list-windows --app "the agent"
```
- Pixel region (x,y,w,h):
```bash
python3 {baseDir}/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):
```bash
python3 {baseDir}/scripts/take_screenshot.py --mode temp --active-window
```
- Specific window id (use --list-windows on macOS to discover ids):
```bash
python3 {baseDir}/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 <App> and tell me what you see": capture to temp, then view each printed path in order.
```bash
bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/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
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1
```
Common patterns:
- Default location:
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1
```
- Temp location (the agent visual check):
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp
```
- Explicit path:
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"
```
- Pixel region (x,y,w,h):
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600
```
- Active window (ask the user to focus it first):
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow
```
- Specific window handle (only when provided):
```powershell
powershell -ExecutionPolicy Bypass -File {baseDir}/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:
```bash
screencapture -x output/screen.png
```
- Pixel region:
```bash
screencapture -x -R100,200,800,600 output/region.png
```
- Specific window id:
```bash
screencapture -x -l12345 output/window.png
```
- Interactive selection or window pick:
```bash
screencapture -x -i output/interactive.png
```
### Linux
- Full screen:
```bash
scrot output/screen.png
```
```bash
gnome-screenshot -f output/screen.png
```
```bash
import -window root output/screen.png
```
- Pixel region:
```bash
scrot -a 100,200,800,600 output/region.png
```
```bash
import -window root -crop 800x600+100+200 output/region.png
```
- Active window:
```bash
scrot -u output/window.png
```
```bash
gnome-screenshot -w -f output/window.png
```
## Error handling
- On macOS, run `bash {baseDir}/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.
## When to Use
<!-- TODO: review -->
## When NOT to Use
<!-- TODO: review -->
© OpenAI · Apache-2.0 · trailofbits/skills-curated