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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- 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.
02 资源文件 10
- 参考文档agents/openai.yaml273 B
- 资产文件assets/screenshot-small.svg1019 B
- 资产文件assets/screenshot.png1.4 KB
- 许可证LICENSE.txt10.5 KB
- 脚本scripts/ensure_macos_permissions.sh1.7 KB
- 脚本scripts/macos_display_info.swift482 B
- 脚本scripts/macos_permissions.swift929 B
- 脚本scripts/macos_window_info.swift3.5 KB
- 脚本scripts/take_screenshot.ps14.8 KB
- 脚本scripts/take_screenshot.py19.2 KB
03 SKILL.md 正文
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
--appto 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
--regionto isolate a single display when needed.
Linux prerequisites and selection logic
The helper automatically selects the first available tool:
scrotgnome-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.shfirst 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
ModuleCachepermission 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, andcommand -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.
04 同仓库更多 Skills
winui-app
Bootstrap, develop, and design modern WinUI 3 desktop applications with C# and the Windows App SDK using official Microsoft guidance, WinUI Gallery patterns, Windows App SDK samples, and CommunityToolkit components. Use when creating a brand new app, preparing a machine for WinUI, reviewing, refactoring, planning, troubleshooting, environment-checking, or setting up WinUI 3 XAML, controls, navigation, windowing, theming, accessibility, responsiveness, performance, deployment, or related Windows app design and development work.
vercel-deploy
Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
security-best-practices
Perform language and framework specific security best-practice reviews and suggest improvements. Trigger only when the user explicitly requests security best practices guidance, a security review/report, or secure-by-default coding help. Trigger only for supported languages (python, javascript/typescript, go). Do not trigger for general code review, debugging, or non-security tasks.
playwright
Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script.
openai-docs
Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains.
netlify-deploy
Deploy web projects to Netlify using the Netlify CLI (`npx netlify`). Use when the user asks to deploy, host, publish, or link a site/repo on Netlify, including preview and production deploys.