Screenshot

JetBrainsOfficialCreated by OpenAIDistributed by JetBrains

Skill
Tool integration
Automation and integrations
Apache-2.0
Low risk
Has scripts

From the author

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.

— the description by OpenAI

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The screenshot skill provides a unified interface for capturing visual data from the operating system. It acts as a fallback or primary tool when application-specific capture methods are unavailable. The skill supports macOS, Linux, and Windows, utilizing Python and PowerShell helpers to manage complex capture requirements like specific window IDs, pixel regions, or active window focus. It includes preflight checks for macOS permissions to ensure smooth operation within sandboxed environments.

What it does

Captures full-screen, specific application windows, or defined pixel regions.
Handles cross-platform screenshot logic for macOS, Linux, and Windows.
Provides macOS-specific preflight checks to manage Screen Recording permissions.
Supports saving screenshots to custom paths, default OS locations, or temporary directories.
Lists active window IDs on macOS to facilitate precise capture.
Includes direct OS command fallbacks for environments where helper scripts cannot run.

When to use it

When a user explicitly requests a screenshot of their desktop or an application.
When you need to perform a visual inspection of an application's state.
When tool-specific capture methods (like browser or Figma integrations) are unavailable.
When you need to compare a design file against the actual rendered output of an application.

Advantages

Unified command structure across different operating systems.
Reduces repetitive permission prompts on macOS via a dedicated preflight script.
Flexible output options including temporary storage for internal agent inspection.
Supports granular capture via window IDs and pixel coordinates.

Usage examples

“Take a screenshot of the current desktop.”: The agent executes the platform-appropriate script and saves the full-screen image to the default location, reporting the file path.
“Capture the 'Settings' window of the Codex app.”: The agent uses the macOS window-capture helper to identify the specific window and saves a screenshot of only that interface.
“Take a screenshot of the region at x=100, y=200 with width 800 and height 600.”: The agent runs the capture script with the specified region parameters and provides the path to the resulting image file.
“Check what is currently visible in the active window.”: The agent captures the frontmost window and saves it to a temporary directory for visual analysis.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/jetbrains/screenshot/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip screenshot.zip -d .agents/skills

Documentation by OpenAI

Screenshot Capture

Follow these save-location rules every time:

If the user specifies a path, save there.
If the user asks for a screenshot without a path, save to the OS default screenshot location.
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 <App> 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:

scrot
gnome-screenshot
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.

Files

ATTRIBUTION.mdAdded by AutoGineer895 B
LICENSE.txt10.5 KiB
SKILL.md7.7 KiB
agents/openai.yaml273 B
assets/screenshot-small.svg1019 B
assets/screenshot.png860 B
scripts/ensure_macos_permissions.shScript1.7 KiB
scripts/macos_display_info.swiftScript482 B
scripts/macos_permissions.swiftScript929 B
scripts/macos_window_info.swiftScript3.5 KiB
scripts/take_screenshot.ps1Script4.8 KiB
scripts/take_screenshot.pyScript19.2 KiB

scripts/macos_window_info.swift

import AppKit
import CoreGraphics
import Foundation

struct Bounds: Encodable {
  let x: Int
  let y: Int
  let width: Int
  let height: Int
}

struct WindowInfo: Encodable {
  let id: Int
  let owner: String
  let name: String
  let layer: Int
  let bounds: Bounds
  let area: Int
}

struct Response: Encodable {
  let count: Int
  let selected: WindowInfo?
  let windows: [WindowInfo]?
}

func value(for flag: String) -> String? {
  guard let idx = CommandLine.arguments.firstIndex(of: flag) else {
    return nil
  }
  let next = CommandLine.arguments.index(after: idx)
  guard next < CommandLine.arguments.endIndex else {
    return nil
  }
  return CommandLine.arguments[next]
}

let frontmostFlag = CommandLine.arguments.contains("--frontmost")
let explicitApp = value(for: "--app")
let frontmostName = frontmostFlag ? NSWorkspace.shared.frontmostApplication?.localizedName : nil
if frontmostFlag && frontmostName == nil {
  fputs("{\"count\":0}\n", stderr)
  exit(1)
}
let appFilter = (explicitApp ?? frontmostName)?.lowercased()
let nameFilter = value(for: "--window-name")?.lowercased()
let includeList = CommandLine.arguments.contains("--list")

let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
guard let raw = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
  fputs("{\"count\":0}\n", stderr)
  exit(1)
}

var exactMatches: [WindowInfo] = []
var partialMatches: [WindowInfo] = []
exactMatches.reserveCapacity(raw.count)
partialMatches.reserveCapacity(raw.count)

for entry in raw {
  guard let owner = entry[kCGWindowOwnerName as String] as? String else { continue }
  let ownerLower = owner.lowercased()
  if let appFilter, !ownerLower.contains(appFilter) { continue }

  let name = (entry[kCGWindowName as String] as? String) ?? ""
  if let nameFilter, !name.lowercased().contains(nameFilter) { continue }

  guard let number = entry[kCGWindowNumber as String] as? Int else { continue }
  let layer = (entry[kCGWindowLayer as String] as? Int) ?? 0

  guard let boundsDict = entry[kCGWindowBounds as String] as? [String: Any] else { continue }
  let x = Int((boundsDict["X"] as? Double) ?? 0)
  let y = Int((boundsDict["Y"] as? Double) ?? 0)
  let width = Int((boundsDict["Width"] as? Double) ?? 0)
  let height = Int((boundsDict["Height"] as? Double) ?? 0)
  if width <= 0 || height <= 0 { continue }

  let bounds = Bounds(x: x, y: y, width: width, height: height)
  let area = width * height
  let info = WindowInfo(id: number, owner: owner, name: name, layer: layer, bounds: bounds, area: area)
  if let appFilter, ownerLower == appFilter {
    exactMatches.append(info)
  } else {
    partialMatches.append(info)
  }
}

let windows: [WindowInfo]
if appFilter != nil && !exactMatches.isEmpty {
  windows = exactMatches
} else {
  windows = partialMatches
}

func rank(_ window: WindowInfo) -> (Int, Int) {
  // Prefer normal-layer windows, then larger area.
  let layerScore = window.layer == 0 ? 0 : 1
  return (layerScore, -window.area)
}

let ordered: [WindowInfo]
if frontmostFlag {
  ordered = windows
} else {
  ordered = windows.sorted { rank($0) < rank($1) }
}
let selected = ordered.first

let list: [WindowInfo]?
if includeList {
  list = ordered
} else {
  list = nil
}

let response = Response(count: windows.count, selected: selected, windows: list)
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys]

if let data = try? encoder.encode(response),
   let json = String(data: data, encoding: .utf8) {
  print(json)
} else {
  fputs("{\"count\":\(windows.count)}\n", stderr)
  exit(1)
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

OpenAI

Publisher

JetBrains (Official)

Distributed by

JetBrains

Source

JetBrains/skills · screenshot · commit 3f53782

Licence

Apache License 2.0 (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by OpenAI or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download screenshot.zip