Agent Skills

1---
2name: "screenshot"
3description: "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."
4---
5 
6 
7# Screenshot Capture
8 
9Follow these save-location rules every time:
10 
111) If the user specifies a path, save there.
122) If the user asks for a screenshot without a path, save to the OS default screenshot location.
133) If Codex needs a screenshot for its own inspection, save to the temp directory.
14 
15## Tool priority
16 
17- 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).
18- Use this skill when explicitly asked, for whole-system desktop captures, or when a tool-specific capture cannot get what you need.
19- Otherwise, treat this skill as the default for desktop apps without a better-integrated capture tool.
20 
21## macOS permission preflight (reduce repeated prompts)
22 
23On macOS, run the preflight helper once before window/app capture. It checks
24Screen Recording permission, explains why it is needed, and requests it in one
25place.
26 
27The helpers route Swift's module cache to `$TMPDIR/codex-swift-module-cache`
28to avoid extra sandbox module-cache prompts.
29 
30```bash
31bash <path-to-skill>/scripts/ensure_macos_permissions.sh
32```
33 
34To avoid multiple sandbox approval prompts, combine preflight + capture in one
35command when possible:
36 
37```bash
38bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
39python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"
40```
41 
42For Codex inspection runs, keep the output in temp:
43 
44```bash
45bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
46python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp
47```
48 
49Use the bundled scripts to avoid re-deriving OS-specific commands.
50 
51## macOS and Linux (Python helper)
52 
53Run the helper from the repo root:
54 
55```bash
56python3 <path-to-skill>/scripts/take_screenshot.py
57```
58 
59Common patterns:
60 
61- Default location (user asked for "a screenshot"):
62 
63```bash
64python3 <path-to-skill>/scripts/take_screenshot.py
65```
66 
67- Temp location (Codex visual check):
68 
69```bash
70python3 <path-to-skill>/scripts/take_screenshot.py --mode temp
71```
72 
73- Explicit location (user provided a path or filename):
74 
75```bash
76python3 <path-to-skill>/scripts/take_screenshot.py --path output/screen.png
77```
78 
79- App/window capture by app name (macOS only; substring match is OK; captures all matching windows):
80 
81```bash
82python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"
83```
84 
85- Specific window title within an app (macOS only):
86 
87```bash
88python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --window-name "Settings"
89```
90 
91- List matching window ids before capturing (macOS only):
92 
93```bash
94python3 <path-to-skill>/scripts/take_screenshot.py --list-windows --app "Codex"
95```
96 
97- Pixel region (x,y,w,h):
98 
99```bash
100python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --region 100,200,800,600
101```
102 
103- Focused/active window (captures only the frontmost window; use `--app` to capture all windows):
104 
105```bash
106python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --active-window
107```
108 
109- Specific window id (use --list-windows on macOS to discover ids):
110 
111```bash
112python3 <path-to-skill>/scripts/take_screenshot.py --window-id 12345
113```
114 
115The 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.
116 
117### Workflow examples
118 
119- "Take a look at <App> and tell me what you see": capture to temp, then view each printed path in order.
120 
121```bash
122bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
123python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp
124```
125 
126- "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.
127 
128### Multi-display behavior
129 
130- On macOS, full-screen captures save one file per display when multiple monitors are connected.
131- 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.
132 
133### Linux prerequisites and selection logic
134 
135The helper automatically selects the first available tool:
136 
1371) `scrot`
1382) `gnome-screenshot`
1393) ImageMagick `import`
140 
141If none are available, ask the user to install one of them and retry.
142 
143Coordinate regions require `scrot` or ImageMagick `import`.
144 
145`--app`, `--window-name`, and `--list-windows` are macOS-only. On Linux, use
146`--active-window` or provide `--window-id` when available.
147 
148## Windows (PowerShell helper)
149 
150Run the PowerShell helper:
151 
152```powershell
153powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1
154```
155 
156Common patterns:
157 
158- Default location:
159 
160```powershell
161powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1
162```
163 
164- Temp location (Codex visual check):
165 
166```powershell
167powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp
168```
169 
170- Explicit path:
171 
172```powershell
173powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"
174```
175 
176- Pixel region (x,y,w,h):
177 
178```powershell
179powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600
180```
181 
182- Active window (ask the user to focus it first):
183 
184```powershell
185powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow
186```
187 
188- Specific window handle (only when provided):
189 
190```powershell
191powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -WindowHandle 123456
192```
193 
194## Direct OS commands (fallbacks)
195 
196Use these when you cannot run the helpers.
197 
198### macOS
199 
200- Full screen to a specific path:
201 
202```bash
203screencapture -x output/screen.png
204```
205 
206- Pixel region:
207 
208```bash
209screencapture -x -R100,200,800,600 output/region.png
210```
211 
212- Specific window id:
213 
214```bash
215screencapture -x -l12345 output/window.png
216```
217 
218- Interactive selection or window pick:
219 
220```bash
221screencapture -x -i output/interactive.png
222```
223 
224### Linux
225 
226- Full screen:
227 
228```bash
229scrot output/screen.png
230```
231 
232```bash
233gnome-screenshot -f output/screen.png
234```
235 
236```bash
237import -window root output/screen.png
238```
239 
240- Pixel region:
241 
242```bash
243scrot -a 100,200,800,600 output/region.png
244```
245 
246```bash
247import -window root -crop 800x600+100+200 output/region.png
248```
249 
250- Active window:
251 
252```bash
253scrot -u output/window.png
254```
255 
256```bash
257gnome-screenshot -w -f output/window.png
258```
259 
260## Error handling
261 
262- On macOS, run `bash <path-to-skill>/scripts/ensure_macos_permissions.sh` first to request Screen Recording in one place.
263- 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.
264- 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.
265- If Linux region/window capture fails, check tool availability with `command -v scrot`, `command -v gnome-screenshot`, and `command -v import`.
266- If saving to the OS default location fails with permission errors in a sandbox, rerun the command with escalated permissions.
267- Always report the saved file path in the response.
268